url-routingpython-sphinxrestructuredtextsectionstargeting

Static alias to auto generated section URLs with ReST / Sphinx


I have a web application with some "Help" buttons which point to my online documentation. The links to the help sections are hardcoded in the app database. Previously, the documentation was made in HTML and JS, and I could control the URLs to the section manually.

However, now that I am migrating to Sphinx and ReST, I found the automatic section URL generation great, but cannot figure out how to control this behaviour for my structure.

Is there a way to have a sort of URL alias which point to the actual URL of my documentation in order not to update the hardcoded links in the app db everytime I update the name of my chapters/sections?

For instance:


Solution

  • See Hyperlink Targets in the docutils documentation, specifically "internal hyperlink targets".

    .. _my-target:
    .. _synonym-to-my-target:
    
    My Subsection
    -------------
    

    Sphinx will generate targets for each synonym.

    You could also do indirect hyperlink targets.

    .. _my-target: synonym-to-my-target_
    .. _synonym-to-my-target:
    
    My Subsection
    -------------