-1

I am writing lots of Sphinx/RestructuredText and this includes Sequence Diagrams using PlantUML. I have lots of text that I am reusing, so to make things cleaner, I created a definitions.iuml file. In this file, I can create named text references (via !startsub/!endsub blocks) that allows me to reference them in several different Sequence Diagrams. Change it once in the source location, and they all change. Perfect.

My problem is how to use these references outside of Sequence Diagrams? I use the exact same code (!includesub ../defintions.iuml!NAMED-REFERENCE) in the .rst file, and when I make docx/pdf, I see that link, I don't see the text that it is referencing. To make things worse, Google has like no documentation or search results on this. Queries of includesub, startsub, endsub +sphinx come back with nothing.

Help me obiwan kenobi.

observer
  • 2,925
  • 1
  • 19
  • 38
Michael Norton
  • 27
  • 8

1 Answers1

0

I found the answer, which only resulted in more questions haha. Anyway, one thing at a time:

  1. To create reference variables in your text document, use rst_prolog or rst_epilog in your Conf.py file. Why there are 2 commands that serve the same purpose, I dont know.

     rst_prolog = """
 .. |Variable1| replace:: Monday
 .. |Variable2| replace:: Tuesday 
 """

Now whenever you write |Variable1| in your text, the document will generate Monday.

  1. The problem with the above is that its just for short words/phrases. You can't use it for code blocks, or anything that is more than one line. To reference in Code Blocks:

  • Create a new .rst file with the code you want to display. Best practice is to create a Code folder and place them all in there.

  • Further best practice is to stop using the '.. code block::' and instead use '.. parsed-literal::'. The output is the exact same, but parsed-literal allows you to use conf.py variables and ..codeblock:: doesn't.

  • So in this .rst file, first line is .. parsed-literal:: and all the text below it is the code you want to reference

  • In the original document that you wanted this code, type:

      <4 spaces indent>.. include:: <Folder/File.rst>

  • Generate your document, and notice how the code is now being reference. You can include this reference all throughout your document.

I will soon be creating a new thread, this time asking how the text body and sequence diagrams can use the same reference. Currently, all text needs one reference, all sequences need another reference, and now we have double updates. Not ideal

Michael Norton
  • 27
  • 8