TextBuilder processing generated images

[codeaide]

I am trying to generate text files from my documentation and I am using the text builder that comes out-of-the-box with Sphinx.

My documentation contains PlantUML files, which I use for generating images and embedding them into the HTML documentation. I'd assume that the text builder skips those files but it encounters an error as shown below.

[app] emitting event: 'build-finished'(UnicodeDecodeError('utf-8', b'\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00

It seems that the text builder is trying to read the PNG file that is generated from the PlantUML file. Is there a way to prevent it?

Also, can I force the text builder to generate a single text file instead of generating a text file for each reStructuredText file?

[jdillard]

Try using the wrapper script mentioned in the README and make sure it can pass arguments. How do you currently have platuml configured?

Also, can I force the text builder to generate a single text file instead of generating a text file for each reStructuredText file?

Not currently, that is still a feature request: #2750

[codeaide]

I have the following configuration in my conf.py to make use of the JAR file directly from the repository so that it works consistently on my development and CI/CD environments and uses the custom skinparam configurations.

# get the path to the plantuml JAR file and configuration file
plantumlJAR = os.path.abspath('./tools/plantuml/plantuml.jar')
plantumlCfg = os.path.abspath('./skinparams.puml')

# construct the plantuml command
plantumlCommand = 'java -Djava.awt.headless=true -jar ' + plantumlJAR + ' --config ' + plantumlCfg + ' -tpng -failfast2'

# plantuml command
plantuml = plantumlCommand

Can I change this configuration to pass on the arguments from the builder or can it be done only using the wrapper script?

Regarding the single text file; without knowing a lot of sphinx internals, I created an extension that extends the sphinx.builders.text.TextBuilder to dump everything into a single file. This is how the extended class looks:

class SingleTextBuilder(TextBuilder):
    """Extend TextBuilder to generate single text file output"""

    name = 'singletext'
    '''Name of the builder'''

    epilog = __('The text file is in %(outdir)s.')
    '''Message emitted upon successful build completion'''

    default_translator_class = TextTranslatorExt
    '''Overriden default translator class'''

    def init(self) -> None:
        super().init()
        # open file for writing
        out_file_name = self.outdir / (self.config.singletext_basename + self.out_suffix)
        out_file_name.parent.mkdir(parents=True, exist_ok=True)
        self.out_file = open(out_file_name, 'w')


    def get_outdated_docs(self) -> str | list[str]:  # type: ignore[override]
        # our builder outputs a single file and hence return an arbitary string here
        return 'all documents'

    def write_doc(self, docname: str, doctree: nodes.document) -> None:
        # block the write_doc from TextBuilder as it writes multiple text files
        pass

    def write_documents(self, _docnames: Set[str]) -> None:
        # first flatten the toctree to make a large tree
        with progress_message(__('assembling single document'), nonl=False):
            docname = self.config.root_doc
            tree = self.env.get_doctree(docname)
            docnames: set[str] = set()
            logger.info(darkgreen(docname))
            largetree = inline_all_toctrees(self, docnames, docname, tree, darkgreen, [docname])

        # next visit the flat tree and dump the contents into output file
        with progress_message(__('writing')):
            self.current_docname = docname
            self.secnumbers = self.env.toc_secnumbers.get(docname, {})

            visitor: TextTranslatorExt = self.create_translator(largetree, self)  # type: ignore[assignment]
            largetree.walkabout(visitor)

            output = visitor.body

            try:
                self.out_file.write(output)
            except OSError as err:
                logger.warning(__('error writing output file %s'), err)

    def finish(self):
        # close the output file and wrap up our work
        self.out_file.close()

This dumps all the contents into a single text file. I had some issues with the todolist directive as the TextTranslator was unable to process it. I simple defined a visitor to ignore it for the time being.

[codeaide]

Solved the PlantUML error by modifying the configuration to remove "-tpng" option. Pasting new configuration below.

# get the path to the plantuml JAR file and configuration file
plantumlJAR = os.path.abspath('./tools/plantuml/plantuml.jar')
plantumlCfg = os.path.abspath('./skinparams.puml')

# construct the plantuml command
plantumlCommand = 'java -Djava.awt.headless=true -jar ' + plantumlJAR + ' --config ' + plantumlCfg + ' -failfast2'

# plantuml command
plantuml = plantumlCommand