Re: [sphinx-users] Variables in reST

[Kevin Horn]

On Tue, Feb 19, 2013 at 4:43 AM, Thomas Güttler <h...@tbz-pariv.de> wrote:

I want to use variables in reST:

Example:

Emails to $EMAIL_SUPPORT are forwarded to .....

I would like to set the variable in setup() of my config.py.

How could this be done?

Gunter (below), is on the right track.

In your conf.py, define a rst_epilog (http://sphinx-doc.org/config.html#confval-rst_epilog).  Also define the variable you want to use (EMAIL_SUPPORT) in you example.

Use regular python string formatting (either %-formatting or .format()) to interpolate your variable value into a "replace" substitution.

Use the substitution in your reST documents.

more specifically:

in conf.py:

email_support = "postm...@notarealdomain.com"

rst_epilog = """

    .. |email_support| replace:: {0}

""".format(email_support)

Then in you reST document:

  Emails to |email_support| are forwarded to .....

When Sphinx processes your documents, it will append the rst_epilog to each document before processing it, so the substitution will be defined for each document, and the replacement text will get inserted just like a normal reST substitution would work.

I realize this seems like a lot of effort for something that seems like it should be simple, but it's the only method I've come up with so far that doesn't involve writing an extension to do this.

An extension wouldn't be terribly difficult by the way.  I think it would just be a matter of creating a custom text role that spits out the value of a config var.  It should be pretty simple to create, though I haven't seen anything like it yet, so perhaps it's not as easy as I think.

 

I found a solution, but don't like it:
The reST files can start with a shebang and an interpreter.
See http://stackoverflow.com/questions/13903691/sphinx-variables

FYI, that SO answer is referring to sphinx-the-search-engine, not sphinx-the-documentation-system.

So that really won't work.

 

  Thomas

--

Kevin Horn

[Guenter Milde]

On 2013-02-25, Kevin Horn wrote:
> On Tue, Feb 19, 2013 at 4:43 AM, Thomas Güttler <h...@tbz-pariv.de> wrote:

...

> An extension wouldn't be terribly difficult by the way. I think it would
> just be a matter of creating a custom text role that spits out the value of
> a config var. It should be pretty simple to create, though I haven't seen
> anything like it yet, so perhaps it's not as easy as I think.

In my view, a new `directive for substitution definitions`__ would be more
in line with the existing reStructuredText syntax. Usually, a rst `role`
changes the meaning of the content while a rst `substitution` replaces the
content.

How about a new directive "echo" that expands environment variables:

.. |LANG| echo:: $LANG

The value of the environment variable LANG is |LANG|.


Günter


__ http://docutils.sourceforge.net/docs/ref/rst/directives.html#directives-for-substitution-definitions

[Kevin Horn]

On Tue, Feb 26, 2013 at 3:11 AM, Guenter Milde <mi...@users.sf.net> wrote:

On 2013-02-25, Kevin Horn wrote:
> On Tue, Feb 19, 2013 at 4:43 AM, Thomas Güttler <h...@tbz-pariv.de> wrote:

...

> An extension wouldn't be terribly difficult by the way.  I think it would
> just be a matter of creating a custom text role that spits out the value of
> a config var.  It should be pretty simple to create, though I haven't seen
> anything like it yet, so perhaps it's not as easy as I think.

In my view, a new `directive for substitution definitions`__ would be more
in line with the existing reStructuredText syntax. Usually, a rst `role`
changes the meaning of the content while a rst `substitution` replaces the
content.

Hmmm.  I'm not sure that I agree with this, though I'm not sure that I disagree with it either.

The main reason I was thinking of a role is because I tend to think of substitutions when I want to make a block-level item into an inline structure, though obviously that's not the only use for them.

A directive+substitution would certainly work, though is more complex.  Assuming for just a moment that I had the option of using either a directive+substitution or a role, I think I would prefer a directive+substitution when the "variable" was repeated several times in a document, and a role when it wasn't.

Maybe it makes sense to have both a role _and_ a directive.

 

How about a new directive "echo" that expands environment variables:

.. |LANG| echo:: $LANG

The value of the environment variable LANG is |LANG|.

I certainly don't care for the name, "echo", though of course that isn't central to your argument.  I'd much prefer something like "expand".

Also, when you say "environment variable", do you mean actual environment variables (like you might see in a shell if you typed "set"), or just variables defined in Sphinx's conf.py?

I had thought we were talking about the latter, though the former is also an interesting idea.  Using actual shell env vars is less Sphinx-specific, and could be used in any docutils processing system , *but* could open up security holes if used improperly.

 

Günter


__ http://docutils.sourceforge.net/docs/ref/rst/directives.html#directives-for-substitution-definitions

--

Kevin Horn

[Guenter Milde]

On 2013-02-26, Kevin Horn wrote:
> On Tue, Feb 26, 2013 at 3:11 AM, Guenter Milde <mi...@users.sf.net> wrote:

>> On 2013-02-25, Kevin Horn wrote:
>> > On Tue, Feb 19, 2013 at 4:43 AM, Thomas Güttler <h...@tbz-pariv.de> wrote:

>> ...

>> > An extension wouldn't be terribly difficult by the way. I think it would
>> > just be a matter of creating a custom text role that spits out the value
>> of
>> > a config var. It should be pretty simple to create, though I haven't
>> seen
>> > anything like it yet, so perhaps it's not as easy as I think.

>> In my view, a new `directive for substitution definitions`__ would be more
>> in line with the existing reStructuredText syntax. Usually, a rst `role`
>> changes the meaning of the content while a rst `substitution` replaces the
>> content.

> Hmmm. I'm not sure that I agree with this, though I'm not sure that I
> disagree with it either.

> The main reason I was thinking of a role is because I tend to think of
> substitutions when I want to make a block-level item into an inline
> structure, though obviously that's not the only use for them.

> A directive+substitution would certainly work, though is more complex.
> Assuming for just a moment that I had the option of using either a
> directive+substitution or a role, I think I would prefer a
> directive+substitution when the "variable" was repeated several times in a
> document, and a role when it wasn't.

> Maybe it makes sense to have both a role _and_ a directive.

You could add a feature request at the Docutils tracker
http://sourceforge.net/tracker/?group_id=38414&atid=422033
so that the idea is not forgotten.

>> How about a new directive "echo" that expands environment variables:

>> .. |LANG| echo:: $LANG

>> The value of the environment variable LANG is |LANG|.

> I certainly don't care for the name, "echo", though of course that isn't
> central to your argument. I'd much prefer something like "expand".

> Also, when you say "environment variable", do you mean actual environment
> variables (like you might see in a shell if you typed "set"), or just
> variables defined in Sphinx's conf.py?

> I had thought we were talking about the latter, though the former is also
> an interesting idea. Using actual shell env vars is less Sphinx-specific,
> and could be used in any docutils processing system , *but* could open up
> security holes if used improperly.

As a Docutils developer, I thought about shell variables. Looking
for Python variables seems at least as security-sensitive as looking for
environment variables.

Günter