CODEWITHSUNDEEP
wikirestructuredtext
Maklaus
Maklaus

Reputation: 688

Using variables in reStructuredText

I'm writing a long HOWTO in reStructuredText format and wondering if there's a way to let user specify values for a couple variables (hostname, ip address) at the top so the rest of the document would be filled with those automatically?

Upvotes: 5

Views: 4728

Answers (2)

Tim
Tim

Reputation: 1805

Like me, you are probably looking for substitution. At the bottom of the section you'll find how to replace text.

Substitution Definitions

Doctree element: substitution_definition.

Substitution definitions are indicated by an explicit markup start (".. ") followed by a vertical bar, the substitution text, another vertical bar, whitespace, and the definition block. Substitution text may not begin or end with whitespace. A substitution definition block contains an embedded inline-compatible directive (without the leading ".. "), such as "image" or "replace".

Specifically about text replacement:

Replacement text

The substitution mechanism may be used for simple macro substitution. This may be appropriate when the replacement text is repeated many times throughout one or more documents, especially if it may need to change later. A short example is unavoidably contrived:

|RST|_ is a little annoying to type over and over, especially
when writing about |RST| itself, and spelling out the
bicapitalized word |RST| every time isn't really necessary for
|RST| source readability.

.. |RST| replace:: reStructuredText
.. _RST: http://docutils.sourceforge.net/rst.html

Upvotes: 10

Timotheus.Kampik
Timotheus.Kampik

Reputation: 2505

reStructuredText is a markup language to define static content. HTML content (I assumed the desired output format is HTML) is typically generated from reStructuredText on build time and then released/shipped to the user.

To allow users to specify variables, you would need a solution on top of reStructuredText, for example:

  • Ship the content with a JavaScript plugin that dynamically replaces specific strings in the HTML document with user input.
  • Generate the documentation on-the-fly after the user has specified the variables.

Note that these examples are not necessarily particularly viable solutions.

Upvotes: 1

Related Questions