Modern Python Projects Transcripts
Chapter: Documentation
Lecture: Setting up Sphinx

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

Talk Python's Mastodon Michael Kennedy's Mastodon