Re: [Docutils-users] How to add index information

[Guenter M. <mi...@us...>]

On 2020-08-28, Alan Williamson wrote:

> Hello,

> I am downloading reStructuredText from our website. These files are
> used along with Sphinx to create the sites on-line (ReadTheDocs)
> documentation.

> I want to ‘tag’ words within the downloaded reST files ahead of
> converting these to XHTML which is used to build the index at the end
> of a generated PDF document. 
> The tagged rest documents are loaded back
> to the sites repository so that the tagging is persisted. 

Mind, that creating an index is not supported by Docutils but an addition by
Sphinx. So, for questions relating to index generation better ask the Sphinx
people.

> So I am looking for a way of adding tags that will be ignored by the
> sites processes.  

The question, how to add information to an rST source that does
not appear in the output is more generic, so I'll try an anwer.

> I need to tag specific words inline so ‘.. Comments’
> will not work, but perhaps there is another way?

More than one with different side effects and preconditions.

What works best depends on your use case, so a minimal example or more
detailed description is required for a more detailed anwser.

> My simple naïve approach was to embed html comments ahead of the
> word(s), for example putting <!—startTag --> before the words and
> <!—endTag --> after them.  This worked for my processes but the
> web-site documentation processes don’t keep these as comments and they
> appear on the screen.

Did you put the HTML comments in "raw" roles?
(In contrast to Markup, rST allows raw HTML only inside a "raw" directive or
role.)

However, I suggest defining a custom role that allows to add class values
to inline text.
Another option would be using substitutions.

I hope this gets you started.


Günter