Very specific too-much-hardcoded code to manage my https://reinout.vanrees.org website.
Install everything initially with:
$ make install
This install also adds some symlinks to the separate (and private!)
../rvo-websitecontent/
directory. For privacy reasons, the ansible
provision/deploy scripts and the nginx config files are in that private repo.
The actual making of the sphinx documentation is done with a make html
inside the docs directory. I do this normally by calling makedocs
(from my
"tools" repo, whose scripts are installed globally).
From time to time people ask me how I've made my blog with sphinx. Also because I've got the top rated answer on stackoverflow for the "weblog with sphinx" question: http://stackoverflow.com/a/1588720/27401 .
Note: there's http://ablog.readthedocs.org/ that uses sphinx and looks quite polished. At least it is currently very much more reusable than my code :-)
Ablog works by marking certain pages as blog posts. My code works from a
yyyy/mm/dd/entry.txt
structure. Ablog also seems to "take over" your
entire sphinx site instead of my code, that hardcodes itself neatly into some
corner :-)
At the "django under the hood 2015" sprint, Eric Holscher pointed me at ablog and also gave me some other tips.
One of the not-standard-sphinx things I do is that I have a "preprocessor
script" that generates index.txt
files in all the subdirectories. It also
generates a tags/tagname.txt
file per tag. All of those files are just a
title and a TOC pointing at the files.
TODO items so I can do to do away with the preprocessing:
I can have a global TOC that automatically includes everything in my weblog directory. Apparently there's a
:glob:
configuration option for TOC, so I probably can put*/*/*/*.txt
in there and delete all myindex.txt
files.Instead of creating
index.txt
and tag "input files" beforehand and letting Sphinx take care of the rest, I can also generate "output files". So programmatically insert docs and nodes (or whatever the sphinx terminology is) into the doctree and let sphinx render it to the output html directory!For this, I need an accurate list, probably inside some sphinx memory structure, of blog posts and tags and their links.
My sphinx "app" registers directives and connects to two signals at the moment. I should enhance this with other signals like
doctree-read
anddoctree-resolved
, I think. Seeablog/__init__.py
for examples. This could do away with the custom scripts I have to call.Actually... I could perhaps even use it to retain my
index.txt
generation, only now I fire it from within sphinx.... :-) For this, thebuilder-inited
event seems best.