For the documentation I have been writing, I couldn't get ifconfig or
replacements to do what I wanted do. I have some variation on how things
work and ifconfig was pretty limited. I didn't like replace either because
it make it difficult to use it in directives. Eg:
.. parsed-literal::
|replaceme|
Doing this would change this from a verbatim block to a text block. So it
would lose all formatting properties (no box, no shading, etc). This also
means code-blocks and other things didn't work. For the above, I could
then do:
.. code-block:: context
{{ variables_from_yaml_context }}
Instead, I've used the sphinx-jinja extension
(https://pypi.python.org/pypi/sphinx-jinja/0.2.1
https://github.com/tardyp/sphinx-jinja). It allows you to store data in
YAML format, and then use that inside of your rst files. That said, it is
one more thing for you learn. It doesn't do everything I want, but it does
enough. It gives you iterators, conditionals, filters and some other
things that will writing documentation with variations easier.
I've submitted a PR against it to make some improvements (adding debugging,
ability to include other files from jinja, etc).
You may find it useful.
On Tuesday, July 26, 2016 at 5:03:23 AM UTC-7, Chris P wrote:
>
> Hello.
>
> I've scoured the docs and don't see anything that will quite do what I'm
> looking for. I've been at this a few days and am hoping someone here can
> help me.
>
> Let's say I'm writing documentation for a pet store software package. I'm
> trying to build two sets of documentation: one for dog/llama owners, one
> for cat owners. I'm building html docs using *make -e html*. This should
> bring in the myPet environmental variable.
>
> If I make a static *.. |myPet| replace:: |myCat|* entry in rst_epilog, I
> get the output I'm after. But I really want to do something like *..
> |myPet| replace:: '|' += os.environ.get('myPet') += '|'*
>
> *Right now, ifconfig has the desired outcome, but replacement (in conf.py,
> rst_epilog) doesn't work. How can I make replacement work (e.g. dynamically
> .. |myPet| replace:: |myCat|)?* *Yes, I could probably hack together a
> sed/awk script to change these lines in conf.py, but there must be a better
> way.*
>
> I would much rather type out:
>
> *Thanks for buying a fuzzy pet who says |myPet|!*
>
>
> rather than something like
>
> *Thanks for buying a fuzzy pet who says *
>
>
>
> *.. ifconfig:: myPet in ('|myCat|')*
>
> * Meow*
>
> *.. ifconfig:: myPet in ('|myDog|')*
>
> * Woof*
>
> *!*
>
>
> *Environment*:
>
> $ printenv | grep "myPet"
> myPet=myCat
>
>
> *conf.py*:
>
>
>> myPet= u''
> def setup(app):
> app.add_config_value('myPet', '', 'env')
>
> myPet += os.environ.get('myPet')
>
> rst_epilog = """
>
> .. |myCat| replace:: Meow
> .. |myDog| replace:: Woof
>
> """
>
>
> *Information.rst*:
>
> This software is designed to run on Windows, Mac OS and Linux.
>
> .. ifconfig:: myPet in ('|myCat|')
>
> In order to install this software, the **Cat** must be installed on
> your system.
>
> .. ifconfig:: myPet in ('|myDog|')
>
> In order to install this software, the **Dog** must be installed on
> your system.
>
>
> *Changelog.rst*:
> * Better pet store algorithm
>
> .. ifconfig:: myPet in ('|myCat|')
>
> * |PETSTOREFeatureNew| Improved meowing sounds
> * |PETSTOREFeatureNew| Improved hissing sounds
>
> .. ifconfig:: myPet in ('|myDog|', '|myLlama|')
>
> * |PETSTOREFeatureNew| Improved slobber effect
>
> * Minor Fixes
>
--
You received this message because you are subscribed to the Google Groups
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at https://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.
