Sphinx alternative for DocBook entities?


#1

Hello all,

I’m currently writing documentation in RST/Sphinx. Years ago, I’d written in DocBook/SGML and really liked being able to set entities for various references that I didn’t want to type out (long file names, long documentation names, references to manuals in our documentation set, etc). We’d throw something like &bdl-ug; into the doc and have it defined to output something like “Blue Dog Linux User’s Guide.”

For the life of me, I’ve not been able to figure out how to do this on the Sphinx side. It may not be possible, but I’m wondering if jinja templating can help (and how) or if there are other suggestions available.

I’m a team of one, but as our company grows, we’ll hire other writers. I want to set this up so it’s easy to use and harder to make silly mistakes/typos for common terms that shouldn’t have to be written out each and every time.

Thanks and cheers!


#2

I may be answering my own question (funny how that happens sometimes, finding the answer once you’ve publicly raised a question), but is using “html_context” within the conf.py file the right way to define these missing variables (aka DocBook entites for title shortcuts)? I want to think it is, but I’d love to hear from others with some success on this front. Will this also work for PDFs I generate?

After a bit more searching, I don’t think this is the answer at all. I now think the answer is to use rst_prolog or rst_epilog to define substitutions in the conf.py file. Anyone with experience doing this?


#3

As you’ve alluded to, sort of, Sphinx/docutils supports substitutions, which I think does what you’re looking for.

With a substituion, you’d write |overlylongname| and when it’s generated, sphinx replaces |overlylongname| with the string you’ve declared. It works across the output types.

You can absolutely declare global substitutions (that will work on all pages) by declaring them in the build conf using rst_epilog. I do it all the time.


#4

Thanks for ensuring that I’m heading in the right direction. :slight_smile: I tried using rst_epilog and rst_prolog yesterday, but kept getting errors. I tried again this morning, after reading your response, and finally got things working. My biggest problem was that I was trying to hyphenate or use underscores in the substitution as |at-ig| instead of |atig|. Once I took out the hyphens/underscores, my rst_epilog substitutions worked like a champ.

Thanks for the helpful reply!