Identityserver4: Documentation version 1.0.0 PDF (2018-05-15) has incorrect document structure

[Jehoel]

Issue / Steps to reproduce the problem

1. Get the release version of the documentation PDF, current version is dated 2018-05-15: https://media.readthedocs.org/pdf/identityserver4/release/identityserver4.pdf
2. Scroll to the Table of Contents page, or look at the Document Structure (Contents) pane in Adobe Acrobat.

3. Observe that all of the headings are flattened under top-level heading 7 "Free and Commercial support":
   

4. The headings should retain their structure as they do in the HTML ReadTheDocs format.

[leastprivilege]

OK - never tried the PDF feature. Do you know how to fix it?

[salem84]

Hi,
I suppose the issue in PDF is due to Sphinx generates TOC in Latex/PDF unlike HTML website; each title in index.rst file produce a single chapter in PDF (also it is only a paragraph).

As I know we can improve it in two different ways:

1. The simplest: we add a section "Documentation" before .. toctree:: Sphinx directive, so the TOC is correct, also there are "fake" chapter before "Documentation". An example is visible in Pelican documentation (HTML / PDF)
2. we insert .. toctree:: after introduction and before other main title in index.rst, so "fake" chapter will be at the end of PDF. An example is visible in Automapper documentation (HTML / PDF)

However I think a general reingineering of TOC must be done in future; I generated a PDF with TOC 2 levels and the result is about 60 chapters... look at identityserver4-s84-test.pdf

Some tips can be grabbed from Autofac and Django documentation.

What do you think about it? I'm always there willing to help you

[brockallen]

Sure, any PRs to allow this to always be updated would be welcome.

[salem84]

I have updated on my fork the docs... you can view at HTML / PDF.
I have changed in index.rst section headers into bullet list.

I apologize for previous commit references in issue history.
If you agree with changes, I'll create the PR

[lock[bot]]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.