Open ynikitenko opened 1 year ago
There is also an option latex_documents, but I never saw a good example of that; I need only one final pdf document, not several ones with different authors etc.
And I had to create the largest header ("Welcome to...") because of this issue https://github.com/readthedocs/sphinx-autoapi/issues/302 .
And one more thing about Markdown hierarchy: '#' corresponds to <h1>
header, which should be the top one. I can't understand why it becomes a subsection then.
Describe the bug
I have three documents from which I create my documentation (they should be its chapters): Introduction (my README from github), Manual (it is in Markdown, because it was easier for me to create a
man
page from that) and Details/Advanced. I join them from index.rst.I want to have both html and pdf documentation. For html the documentation for my project looks good, and links hierarchy in the toctree is correct.
Unfortunately, for
make latexpdf
section numbering is broken: the manual is grabbed fromtoctree
and inserted as a subsection 1.7.1 instead of chapter 2.0. To get a proper section numbering, I have to insert chapters in LaTeX manually with directivesraw
andonly
. Unfortunately, the sections fromtoctree
still remain inserted, and there is no way to useonly
to prevent that.It seems a bug of
latexpdf
, because forepub
it works correctly. Is there a workaround?How to Reproduce
Environment Information
Sphinx extensions
Additional context
It is strange that I have to use
it was not documented in Sphinx, but without that it breaks.
It is sad that only works only for content. I found some other bugs which explain more why it is so (maybe they should be linked from the documentation?): https://github.com/sphinx-doc/sphinx/issues/9819, "toctree does not consider "only" directive" (with that I could had created two toctrees for pdf and all other formats), https://github.com/sphinx-doc/sphinx/issues/10642#issuecomment-1186146698 (more details about only directive).
Also it is sad that while my manual from Markdown is inserted as a separate section, its internal hierarchy is still broken (instead of being subsections, its parts become sub-subsections; I know no way to fix that). Maybe one time I will convert Markdown to rst, but first I will have to check how it would affect the manual page.