Hello,
I am new to the docutils topic. I want to include confluence (wiki) pages into a sphinx documentation. This is to give developers the choice to write their texts either in .rst files OR in the wiki. The wiki is always available for the customers, but the documentation built with sphinx is currently only available in the delivered software product because of some legal restrictions. If confluence pages can be included into the sphinx documentation, this would spare the developer the effort to write and maintain the same information in two different places. I already have a solution, using the REST API to download the page and its content and include the HTML syntax into the sphinx documentation using the .. raw:: directive: http://docutils.sourceforge.net/docs/ref/rst/directives.html#raw-data-pass-through My current solution requires the html files to be saved temporarily, so it can be included using the following syntax in an .rst file: MyConfluenceContent ------------------- .. raw:: html :file: MyConfluenceContent.html I want to extend this by creating a custom sphinx extension, introducing a new directive ‘Confluence’: MyConfluenceContent ------------------- .. confluence:: <PageID> Because of already existing other confluence related extensions I already have a vague imagination of how the extension could be used. I began to read the tutorials provided by Sphinx to learn how to write custom extensions: https://www.sphinx-doc.org/en/master/development/tutorials/helloworld.html This tutorial talks about modifying already extisting nodes in the docutils package to do what is desired. For my problem I guess I must adapt the ‘raw’ node to my intended usage. The node should not have the option ‘file’. Instead the html code, which will be delivered by my already existing code using the page id should be directly used without saving it to a file first. I have something like this in mind: 1. Use the Confluence REST API to download the HTML content of the page into a local variable 2. Download all images and save them somewhere temporarily 3. Replace the image links in the html code 4. Replace the links in the html code 5. Advise sphinx where to store the local image files 6. Pass the html code directly into the docutils pipeline by somehow adapting the ‘raw’ node for this usage. Sadly the documentation of the raw node is not very extensive, so I don’t know where to begin: http://docutils.sourceforge.net/docs/ref/doctree.html#raw I already looked into the files, but the raw node only seems to inherit from all sorts of other nodes, so I don’t know what to give into its constructor: class raw(Special, Inline, PreBibliographic, FixedTextElement): """ Raw data that is to be passed untouched to the Writer. """ pass Is there someone who at least can tell me if my guess with the ‘raw’ node is correct and where to start? Thank you very much for your help! Sincerely, Dirk Baumbach -- You received this message because you are subscribed to the Google Groups "sphinx-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/6ae44f43-3546-4771-8b4b-eeab11fe45cd%40googlegroups.com.
