You've just finished your latest development masterpiece. Now you have to go back and document it or find someone who likes to write way more than you do to do that job. What are the chances that your documentation will happen, let alone happen well? Not good?
Have you tried to learn to use a code library or had to maintain someone else's code and cursed the lack of documentation, when good documentation would have saved you hours of trial and error writing and re-writing code to figure out how the software works? Worse yet, have you ever failed to document code properly, forgot you wrote that code, then cursed yourself for not writing good documentation?
I have the cure.
On your next development project, take much of the pain out of documentation. Use Sphinx.
According to its home page, Sphinx is a tool that makes it easy to create intelligent and beautiful documentation. It eliminates the need for you to create and maintain separate documentation source files. No more getting documentation out of sync with your code. Sphinx can read your source code and automatically produce documentation. With a little self-education, you can learn to make the documentation even better. Read on to learn how to install it and start learning to write documentation with it.
Languages Sphinx can document include:
- Python
- C
- C++
Sphinx originally documented code in HTML format, but it can also produce output in other formats including PDF and Windows Help.
Sphinx is written in Python, which means that you already need to have Python installed on your system. specifically, Python 3.
The Sphinx Installation instructions explains how to obtain and install it on Mac and Linux.
To install on Windows, I recommend that you follow this procedure:
- Install the Chocolaty package manager.
- Use Chocolaty to install Python and Sphinx.
Installing Chocolaty will allow you to easily install and upgrade a lot more programs. You need to run either PowerShell or Cmd as an administrator to do that.
- See this page on how to run PowerShell as an administrator.
- See this page on how to install The Chocolaty Package Manager.
If Python isn't on your windows system, you can install it after you've installed Chocolaty. Get a PowerShell or command prompt as an administrator and type this command.
choco install python
Now that you have Python installed, from the command line, type this command to install Sphinx.
pip install -U sphinx
This installs Sphinx on your computer for only your user ID.
After you've installed sphinx, you can use this command to verify that you have installed it correctly.
sphinx-build --version
If the version number appears on your screen, you've installed everything correctly. You can now start using Sphinx to document your code.
I mentioned that Sphinx can read your code and produce documentation. To fully use its potential, though, you need to learn reStructuredText. See this full restructuredText reference.
If you prefer to use Markdown to document your code, Check out this page to find out how. See This Markdown guide to learn or brush up on Markdown.
If learning restructuredText or Markdown stops you from experimenting with Sphinx, you could try the following to encourage you to go deeper into learning it:
- Read the Getting Started and try some of the sample documentation there on your code. Check out the resulting documentation
- Run Sphinx against a library file on your system produced by the makers of Python, then look at the source and compare that to the documentation to see what tricks you can pick up to add to your own code documentation.
- Play with producing a static website on your local computer with it.
Let me encourage you with a workflow suggestion. When you know some piece of code you're working on does what it's supposed to do, use your newly acquired knowledge about Sphinx to take that final step of documenting it. Your teammates will thank you. The development world will thank you. You will thank yourself if you ever need to maintain your own code.
I hope this post has helped you document your code.
I welcome any feedback.
This post was originally written at https://www.jimhomme.com