0

I'm creating a Sphinx extension that generates a pretty huge number of RST files.

Since I formally know the content of them, I'd like to gain time and space by directly writing the docutils, skipping the RST generation and parsing of them.

Is there a way to directly write doctree files and integrate them into my Sphinx documentation?

mzjn
  • 48,958
  • 13
  • 128
  • 248
Oragon Efreet
  • 1,114
  • 1
  • 8
  • 25
  • What does "directly writing the docutils" mean? What are "doctree files", as opposed to RST files? – mzjn Mar 17 '23 at 07:05
  • RST is the writer-facing format for describing documents. They are first parsed into Docutils (and serialized to .doctree files) before rendered into a final format such as HTML. – Oragon Efreet Mar 20 '23 at 09:57
  • I'm still confused. Are you referring to "doctree pickles"? https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-d – mzjn Mar 20 '23 at 09:59
  • Yup, i'm talking about them. – Oragon Efreet Mar 20 '23 at 10:54
  • AFAIK, a doctree is a Sphinx/Docutils data structure that represents the contents of an RST file. Are you asking if it is possible to generate HTML output directly, without having to read or write RST files on disk? – mzjn Mar 20 '23 at 11:01
  • Not quite. DocUtils is an abstraction of your documents once they are parsed from RST. Or from any other input source given you have the associated parser. It's also a Python library for writing such DocUtils. My extension generates a pretty decent number of documents. I programmatically write the RST files for them and wonder how I can use Sphinx API to, instead, directly provide them in DocUtils instead of RST so that I gain build time by avoiding the read/parse RST step. – Oragon Efreet Mar 20 '23 at 16:27
  • 1
    I don't think it's impossible to do what you want, but I am not sure that anyone is willing to write the Python code for that from scratch. Edit the question to clarify exactly what you want. Post some code that shows what you have tried so far and where you are stuck. – mzjn Mar 20 '23 at 17:11
  • I'll try to spend more time on this. I don't have anything more to add to the question though, tbh. Thanks! – Oragon Efreet Mar 21 '23 at 09:56

2 Answers2

0

There's an external table of contents plugin that might be easier to work with than the toctree entries? I'm not exactly sure of your use case but you might be able to generate the navigation as well as the files.

Lorna Mitchell
  • 1,819
  • 13
  • 22
0

This is what i'm looking for: https://github.com/sphinx-doc/sphinx/issues/1139. It's not a working feature for the moment.

Oragon Efreet
  • 1,114
  • 1
  • 8
  • 25