Get your team started on a custom learning journey today!
Our Boulder, CO-based learning experts are ready to help!
Get your team started on a custom learning journey today!
Our Boulder, CO-based learning experts are ready to help!
Follow us on LinkedIn for our latest data and tips!
If you’ve ever looked at the Python documentation, you’ve seen Sphinx in action.
Sphinx is an open-source project that allows people to automatically generate static websites for Python documentation. Besides code-heavy documentation, it can also be used as a static site generator.
Sphinx is a Python project that takes in reStructuredText and outputs static web pages. It is most commonly used to host documentation. With Sphinx installed, you can write comments in your code similar to how you would with JavaDoc, and it will pull in all those comments to provide a big picture of your functions and classes. This can be extremely helpful as a programming reference, and since it pulls directly from the code, you don’t have to worry about it getting out of sync.
Sphinx was originally created to host the official Python documentation, but it’s only grown from there. Many popular libraries use Sphinx to host their documentation, and it’s become something of an industry standard among Python developers.
In addition, the popular documentation site Read The Docs makes this process even easier by allowing developers to host and update their Sphinx docs by connecting the repository and building the docs just like you would code. This “docs-as-code” approach helps ensure maximum compatibility between the code and the documentation, and helps mitigate documentation debt.
Here are some notable companies or libraries using Sphinx to host their websites or documentation:
It doesn’t stop at just documentation. Some people have written their personal sites, courses, or even whole books using Sphinx:
Now that you know about all the great things Sphinx can do, I bet you’re wondering how you can use it in your work. Sphinx is adaptable enough to work for many use cases, but it really shines at documenting code, Python code in particular.
If you’re writing Python software as part of your job and having trouble maintaining the docs (or God forbid, you don’t have any docs!), Sphinx is definitely worth a try. It’s free, open source, and there are a variety of resources and tutorials out there to help you customize it to your needs.
Sphinx is great when you have structured information. In this way, Sphinx might not be such a great choice if you’re trying to host your latest novel, but it is a good idea for technical manuals with a complex table of contents that people will need to navigate. Another great feature of Sphinx is that it comes with search built-in, so you don’t have to worry about pulling in another package to do the heavy lifting for you.
Ready to get started? Let’s go through the basics of installing and setting up your first Sphinx site.
You can install Sphinx from PyPI (Python Package Index) by running this command:
$ pip install Sphinx
Once Sphinx is installed, run sphinx-quickstart from your project folder to initialize a project there:
$ sphinx-quickstart
$ make html
The output files should be in _build/html. Navigate there now:
$ cd _build/html
The home page for our site is index.html. Open that file in a web browser to see the example project:
$ open index.html
You should see the basic layout of your new Sphinx site.
Congratulations! You have Sphinx up and running.
For next steps on how to add posts and customize Sphinx, I recommend Brandon’s Sphinx Tutorial (PDF). It’s both informative and easy to follow.
Now that you know about Sphinx, go out there and Write The Docs!
Customized Technical Learning Solutions to Help Attract and Retain Talented Developers
Let DI help you design solutions to onboard, upskill or reskill your software development organization. Fully customized. 100% guaranteed.
DevelopIntelligence leads technical and software development learning programs for Fortune 500 companies. We provide learning solutions for hundreds of thousands of engineers for over 250 global brands.
“I appreciated the instructor’s technique of writing live code examples rather than using fixed slide decks to present the material.”
VMwareDevelopIntelligence has been in the technical/software development learning and training industry for nearly 20 years. We’ve provided learning solutions to more than 48,000 engineers, across 220 organizations worldwide.
Thank you for everyone who joined us this past year to hear about our proven methods of attracting and retaining tech talent.
© 2013 - 2022 DevelopIntelligence LLC - Privacy Policy
Let's review your current tech training programs and we'll help you baseline your success against some of our big industry partners. In this 30-minute meeting, we'll share our data/insights on what's working and what's not.
Training Journal sat down with our CEO for his thoughts on what’s working, and what’s not working.