search

vovkos / doxyrest

A compiler from Doxygen XML to reStructuredText -- hence, the name. It parses XML databases generated by Doxygen and produces reStructuredText for the Python documentation generator Sphinx.
MIT License
306 stars 23 forks source link

Outputting just rst without Sphinx extension #32

Closed cadop closed 4 years ago

cadop commented 4 years ago

I ended up finding your repo while on my search to convert the c# doxygen xml output to rst for sphinx, so this is somewhat the mindset for my questions. From the motivation stated, it seems that I can write a single lua file to support c#, which is a nice solution for the bridge between the two.

The Architectural Overview https://vovkos.github.io/doxyrest/manual/architecture.html shows doxyrest taking the xml and outputting rst. Then rst gets pulled from Sphinx. However it doesn't explain the logic for modifying the sphinx config.py file or needing an extension.

Why is this needed?

vovkos commented 4 years ago

Re Sphinx extensions:

The Doxyrest extension is required for the proper translation of generated RST files. It defines a few roles (e.g., target, which marks an inline target) and directives (e.g ref-code-block, which generates a highlighted code block with links), which Doxyrest-generated RSTs rely upon.

The second extension (cpplexer) is not essential, but it addresses a few issues with the standard C++ lexer from pygments. For example, it fixes the improper colorization of single-line comments, preprocessor directives when these happen to be at the end of a code-block. Also, it doesn't attempt to colorize escape sequences within string literals, which is broken in pygments anyway.

TL;DR: doxyrest extension is required for the RSTs generated by Doxyrest; cpplexer is optional, but recommended.

Re C#:

Since C# belongs to the C-family, I would re-use most of the RST frames for C/C++; the general structure of the source-item tree is going to remain the same. What is going to change, is some minor language-dependent details of declaration syntax (implemented is frame/cfamily/utils.lua).