Sphinx Docs Made Simple
I broke into the dev world as a docs person. So, when the company I’m currently doing development work for asked me to generate some docs posthaste, I went right back to this awesome post by Sam Nicholls that made the process seem pretty straight forward — even then.
As awesome as the above post is, I figure it might be nice to have an even simpler breakdown of the steps from zero to auto-generated doc goodness. So, here goes.
Although Sphinx supports a number of different languages, odds are you are working with Python if you’re here, so let’s start there.
- First things first, install Sphinx:
pip install sphinx. (I use Pipenv, but you don’t have to).
2. Then create a docs directory in your repo.
3. Next, from within that directory, run sphinx-quickstart.
4. After that, run sphinx-apidoc -o source/ ../<repo root dir> in order to generate the “stubs” that Sphinx will use to actually generate the docs. NOTE: you may need to adjust the ../<repo root dir> portion according to the actual depth of your file tree.
5. Okay, home stretch. Now in a text editor of your choice, open the auto-generated conf.py file that should now be in your docs directory. Very near to the top of the file, you should find the following line:
sys.path.insert(0, os.path.abspath('.'))
Simply uncomment that line and save.
6. Finally, still from within the docs directory, run: sphinx-build . _build.
And Shazzam! You should now have some neat, interactive docs.
