Hi,
It seems your approach is okay to me. raw node is useful to generate
contents for specific format.
>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:
Let's take a look all of base classes. Special, Inline and
PreBibliographic are called "Element Categories". And they are used
only for category. So they don't have any concrete methods. The last
base class, FixedTextElement has a concrete implementation:
```
class FixedTextElement(TextElement):
"""An element which directly contains preformatted text."""
def __init__(self, rawsource='', text='', *children, **attributes):
TextElement.__init__(self, rawsource, text, *children, **attributes)
self.attributes['xml:space'] = 'preserve'
```
The rawsource parameter is an original form of content. In Sphinx, it
is mainly used for translation. Empty string is okay if not needed.
And second parameter "text" is a content of the node. In your case,
HTML content should be given here. Next, children is child nodes of
the new node. But raw node should not have any child nodes. Last
parameter, attributes is important for raw node. "format" attribute is
required for the node.
So you can generate raw node with following code.
```
node = nodes.raw('', html, format='html')
```
I hope you make your own extension :-)
Thanks,
Takeshi KOMIYA
2019年10月15日(火) 16:31 'Dirk Baumbach' via sphinx-users
<[email protected]>:
>
> 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.
--
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/CAFmkQANGf0rmB_6w7Ha1_xT3vXmA_XET0tuqHVZQHS99TzGRUQ%40mail.gmail.com.
