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 conf.py 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.