separate pages for table of contents and each module in project

[Phillip-M-Feldman]

I have a project that includes ~12 modules, with the number expected to grow over time. Instead of getting one enormous page that includes documentation for all 12 modules, I'd like to get a table-of-contents page that shows the name of each module and a short description, with each module name linking to a separate page containing the documentation for that module. I understand that there is currently no mechanism for doing something like this with Sphinx.

[Phillip-M-Feldman]

I've created an example, including both input and output files, that illustrates what I view as three major deficiencies of Sphinx formatting (I'm guessing that these issues affect not only html, but other output formats as well):

(1) The left-hand roughly 1/3 of the document is empty, wasted space.

(2) The names of modules are displayed in a small, inconspicuous font that makes it easy to miss what should be chapter headings in the document. A possible solution would be to use a much larger font and to put a horizontal line above the heading.

(3) The current format impedes navigation. This could be solved by doing the following: (a) Put an outline-format table of contents with clickable entries at the top of the document. (b) Assign consecutive integers to each module, with these numbers appearing immediately to the left of the module name (e.g., "1. Combinatorics"), both in the table of contents and in the body of the document.

issue_6043.zip

[tk0miya]

(1) The left-hand roughly 1/3 of the document is empty, wasted space.

You can switch HTML themes to one not having sidebar.
https://www.sphinx-doc.org/en/master/usage/theming.html#themes

(2) The names of modules are displayed in a small, inconspicuous font that makes it easy to miss what should be chapter headings in the document. A possible solution would be to use a much larger font and to put a horizontal line above the heading.

autodoc does not generate any headings. It's plain content. So you need to write headings by your hand.

[Phillip-M-Feldman]

I added the following to my conf.py: html_theme = 'classic' html_theme_options = {'nosidebar': True} With these changes, the output is much cleaner looking, but roughly 40 percent of the screen on the right is wasted (solid color), as shown below: [image: NGPP formatting issues.png] Note also the size of the heading "combinatorics.py". The corresponding line of html looks like this: <p>combinatorics.py</p> Given that combinatorics.py is one of the four modules in the project, this should probably be a level-1 heading. In fact, if I edit the html by hand and change the above line to <h1>combinatorics.py</h1>, I get output that looks more reasonable: [image: NGPP formatting issues 2.png] Is there any way to address these two issues without manually editing the html? Thanks! Phillip

…

On Sun, Mar 31, 2019 at 7:41 AM Takeshi KOMIYA ***@***.***> wrote: (1) The left-hand roughly 1/3 of the document is empty, wasted space. You can switch HTML themes to one not having sidebar. https://www.sphinx-doc.org/en/master/usage/theming.html#themes (2) The names of modules are displayed in a small, inconspicuous font that makes it easy to miss what should be chapter headings in the document. A possible solution would be to use a much larger font and to put a horizontal line above the heading. autodoc does not generate any headings. It's plain content. So you need to write headings by your hand. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#6043 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABBBxPZgYOem13EbiGh_r0-dDhXDh8yIks5vcMkhgaJpZM4ayRRD> .

[tk0miya]

With these changes, the output is much cleaner looking, but roughly 40
percent of the screen on the right is wasted (solid color), as shown below:

I think body_max_width = none for html_theme_options will help you. If not, you need to make a your own theme.

Note also the size of the heading "combinatorics.py". The corresponding
line of html looks like this:

I don't know how you are marking up it. But sphinx does not consider it is a heading.

Note: Sphinx considers the following marked up text is a heading

heading title
=============

[Phillip-M-Feldman]

You are correct on all counts. Thanks! FYI, although the documentation says that the value corresponding to the key 'body_max_width' must have type int or str, the value `None` also works. I have two residual questions: (1) Is there any way to increase the size of class, function, and method names? (Note the small size of the function name at the bottom of the screen shot below). (2) Is there any way to prevent Sphinx from putting the functions in alphabetical order? (I would like the order of the functions in the documentation to be the same as in the code). [image: image.png]

…

On Tue, Apr 2, 2019 at 10:14 AM Takeshi KOMIYA ***@***.***> wrote: With these changes, the output is much cleaner looking, but roughly 40 percent of the screen on the right is wasted (solid color), as shown below: I think body_max_width = none for html_theme_options will help you. If not, you need to make a your own theme. Note also the size of the heading "combinatorics.py". The corresponding line of html looks like this: I don't know how you are marking up it. But sphinx does not consider it is a heading. Note: Sphinx considers the following marked up text is a heading heading title ============= — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#6043 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABBBxC69ym12ctw2kSnVg8bnMSmSQa_Fks5vc4_wgaJpZM4ayRRD> .

[Phillip-M-Feldman]

I found the solution for (2), so that leaves only the following:

(1) Is there any way to increase the size of class, function, and method names?