search

artefactual / atom-docs

Access to Memory (AtoM) documentation
https://www.accesstomemory.org/docs
Creative Commons Attribution Share Alike 4.0 International
17 stars 26 forks source link

Add path for settings #293

Closed eviau-artefactual closed 1 month ago

eviau-artefactual commented 1 month ago

Closes https://github.com/artefactual/atom-docs/issues/291

Maybe this is not a good use case of the rst_prolog feature - https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_prolog ... let me know ?

fiver-watson commented 1 month ago

it may work, but reading about in the doc, it is not meant for random in-line subsitutions, but rather for adding static header (prolog) or footer (epilog) content that you want appended to every page. At least that is how I understand it:

rst_prolog

  • Type: str
  • Default: ' '

A string of reStructuredText that will be included at the beginning of every source file that is read. This is a possible place to add substitutions that should be available in every file

E.g. one possible use would be our CC license (though that is already in the website footer, so technically it is in fact visible on every page), or a docs version etc.

If they change this feature to enhance its intended use this way in future versions of sphinx-docs, that could cause problems? Just a thought...

eviau-artefactual commented 1 month ago

I am trying to see if this is a good case to start reusing content to help with the unique feature of source...

Maybe it's too much for this path...?

fiver-watson commented 1 month ago

I think you actually answered your own question though with your links! The RST substitution is a general purpose solution for in-line changes like you were trying to implement. In fact we have used it before (I used it to swap in the header icons into the section titles on the Navigate page), I had just forgotten.

On the other hand, the rst_prolog and epilog functions are specifically for page headers and footers that have repeated content.

I would recommend using the substitution for what you've tried to do here instead, personally.