Modern Python Projects Transcripts
Lecture: Setting up Sphinx
0:01 To install SPHINX were going to run.
0:02 pip install SPHINX without this -u.
0:06 As always, we have to create virtual environment.
0:09 I already have one called Documentation Chapter,
0:12 so let's copy this instruction. Let's remove -u, -u installs packages for given user
0:17 So if you have multiple accounts on your computer,
0:20 it might make sense to use it.
0:22 But since we're using virtual environments,
0:24 we absolutely don't need this value.
0:26 Well, this parameter, okay, sphinx is installed.
0:30 Now we can run Sphinx. Quick start docs command.
0:35 This command will ask you a few questions,
0:37 and it will generate the scaffolding of your documentation.
0:40 So it's pretty similar to what cookie cutter does.
0:43 First, you need to select if you want to have separate directories for the source code
0:48 of your documentation and for the generated files by default things wants to put everything
0:54 into one folder. But just to show you what's the difference between the source and
0:58 build directories, I'm going to select the separate option.
1:01 Next. We need the project name that we're going to use in the documentation. Authors
1:10 name. And then you can specify what's the version of your project?
1:16 Let's say 1.0, If you're writing the doccumentation in a different language than English,
1:21 you can select different language code.
1:24 I will leave to default English value and that's it.
1:27 As you can see, SPHINX has created four files for us.
1:31 The conf.py that stores the configuration for things, index .rst,
1:36 which is your first documentation page and then Makefile and makefile.bat,
1:42 makefile.bat is the make file on Windows,
1:44 and the make file contains commands that you will use to build documentation.
1:49 We now have everything set up to use SPHINX,
1:52 but we don't have any documentation yet.
1:54 To actually generate some documentation from the source files.
1:57 We have to run this make builder command.
2:01 We're builder stands for whatever format we want to generate so it can be there html
2:06 LaTeX, link checks or whatever. So let's generate the HTML documentation.
2:14 Make sure you are inside the Docs folder and then run make html.
2:20 If there were no errors, you will see this message that built has succeeded.
2:24 Your built might fail. For example,
2:26 if you're linking to some files that actually don't exist and things can't find them,
2:32 in this case, you will see the list of errors and the HTML pages won't be
2:36 generated. So now let's go inside the HTML folder.
2:44 And as you can see, we have index html.
2:46 Let's open this in the browser and voila!
2:49 This is the documentation for your project.
2:52 There is not much going on here yet.
2:54 We only have some placeholders that Sphinx has generated.
2:57 So in the next lesson will actually add some real content.