The Painless Way To Contribute To The Cure For Bad Documentation
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.
What Is 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
Languages Sphinx can document include:
- Python
- C
- C++
Documentation Formats
Sphinx originally documented code in HTML format, but it can also produce output in other formats including PDF and Windows Help.
Installing Sphinx
Sphinx is written in Python, which means that you already need to have Python installed on your system. specifically, Python 3.
To install on Windows, I recommend that you follow this procedure:
- Get a Command or PowerShell prompt as an administrator
- Install the Chocolaty package manager.
- Use Chocolaty to install Python and Sphinx.
Getting a Console Prompt As An Administrator
To get a console prompt as an administrator, Press WINDOWS+R, type either cmd or powershell, and press CTRL+ENTER.
. A dialog will ask if you want to allow this app to make changes to your syste. Click Yes.
Installing Chocolaty
Installing Chocolaty will allow you to easily install and upgrade a lot more programs. Copy the code from the page in the link in the previous sentence to do that and run it.
Installing Python
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
The Command To Install Sphinx
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.
Using Sphinx To Write Documentation
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.
Final Words Of Encouragement
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
