Revisting (the) Sphinx and the reST of the Story...
Ok, now, create software with such kick-ass interface that it ships without docs. And, open out the APIs already!
While at that, ensure two parts to it:
Documentation minus fluff plus extensive parameter definitions.
A ton of testable APIs!
Only then shall we be superheroes as cool as The Avengers and cronies or more! Am yet to reach stage-2, but shouldn’t hesitate to add some Swagger soon ;)
API documentation and static site generation is a kind of child’s play with Sphinx - why hop when you can fly! Right? Learning to write the doc source code in reStructuredText (reST) is some amount of work, but the kind of satisfaction for something so lean and easy is totally worth it.
How to...
My method is essentially, do it and repeat it.
(One time) - Run sphinx-quickstart command to generate the framework - makefile, conf.py, _index.rst, etc.
Manually write the source in reST.
(Ongoing) - Add necessary overrides to theme_overrides.css and conf.py
Run sphinx test build on my totally crappy Dell (ubuntu 14.04) work laptop.
Check source into Git when satisfied.
Pull the source into the staging VM.
Make HTML.
Preview and fix again. Checkin if any changes to source.
Pull the source in the Prod box and build HTML again.
This automatically publishes on our Website. Ta da!
... aaaaaand, repeat when necessary.
Sphinx CSS Overrides
Why and how I chose Sphinx for API documentation is a story for another day. For today, am going to focus on some extensive CSS overrides and workarounds that should allow you to customize the theme to satisfaction and get your doc Website rolling. You may find some of these on the Web on various Sphinx or technical forums, but many of them are new.
Am on an older version of the sphinx_rtd_theme. The new one comes with some of these resolved, but I like the older CSS for some basic reasons. I have a separate theme_overrides.css to accommodate for this.
CSS Override - Table Width, Text Wrap, Scroll
The default sphinx_rtd_theme seems to make all tables render with scroll bars, no text wrap. My requirement was to wrap text for all normal tables, and have scroll for really wide tables that go out of view.
/* override table width restrictions */
.wy-table-responsive table td, .wy-table-responsive table th { white-space: normal !important; }
.wy-table-responsive { margin-bottom: 24px; max-width: 100%; overflow: auto !important; }
/* wide table scroll-bar */
table.scrollwide { display: block; width: 700px; background-color: #E0; overflow: scroll; !important } table.scrollwide td { white-space: nowrap; }
Navigation Sidebar Scrolling
In the older theme, the navigation sidebar had no vertical scroll bar for long ToCs. So, if you’d scroll to read the HTML page content, the ToC may scroll out of view.
/* override navigation sidebar out-of-view on page scrolling */
.wy-nav-side {
position: fixed; padding-bottom: 2em; width: 300px; overflow-x: hidden; overflow-y: scroll; min-height: 100%; background: #343131; z-index: 200;
}
Navigation Header Background Color
The hex code for the default blue is #2980B9. You can change it to anything you’d like.
/* changed side navigation bg color */
.wy-side-nav-search {
background-color: #005387 !important;
}
Navigation Menu Overrider: Margins, Text Color, Background Color
These are minor, misc. changes.
/* override navigation menu caption and link text colors */
.wy-menu-vertical .caption-text { color : #7e7e7e; } .wy-menu-vertical a { color : #f0f0f0; }
/* override caption margins */
.wy-menu-vertical p.caption { margin-top: 20px; margin-bottom: 5px;
/* margin-left: 10px; */
}
Override Home Icon
This was, by far, the trickiest for me to figure out. My excuse? Am not a CSS person. Tool help from our UI folks here and done!
/* hide icon-home */
.fa-home:before, .icon-home:before {
content: none; }
/* override fa-home with logo */
.wy-side-nav-search>a:hover { background-image: url("logo.png") !important; background-size: 30px 30px; padding-left: 35px; padding-bottom: 10px; padding-top: 6px; background-repeat: no-repeat; }
.wy-side-nav-search>a { background-image: url("logo.png") !important; background-size: 30px 30px; padding-left: 35px; padding-bottom: 10px; padding-top: 6px; background-repeat: no-repeat; }
Conf.py Changes
Very simple. Ensure that you’ve pointed to the theme you’re using and then add the following references.
Favicon setting
My favicon (the home icon too) is in the static folder.
html_static_path = ['static', 'images'] html_favicon = 'favicon.ico'
Overrides CSS Reference
def setup(app): app.add_javascript("custom.js") app.add_stylesheet("theme_overrides.css")
If you’ve created separate override files, no issues, just replicate the same reference structure pointing to your filename.
You can see my W.I.P. here.
Much like its Egyptian predecessor, this Sphinx won’t disappoint you :) Bon voyage!