Change the display of headings

[Jiji98]

As seen from the attachment provided below, headings are hidden. For example a user looking for how to play for an audience (Heading 6.1.2) and checking in the user manual will have to go through many chapters before realising it is actually in chapter 6. Many people don't like reading user manuals because they are often boring with too many writtings. So I think subheadings should be effectively displayed in the manual such that the user knows exactly where to look for what he needs.

[Anisha-28]

hi @Jiji98 i am an outreachy applicant, i can have a look at this issue

[Jiji98]

Hello I'm an outreachy applicant too

Le dim. 11 oct. 2020 à 05:55, Anisha-28 notifications@github.com a écrit :

hi @Jiji98 https://github.com/Jiji98 i am an outreachy applicant, i can have a look at this issue

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/mixxxdj/manual/issues/144#issuecomment-706649997, or unsubscribe https://github.com/notifications/unsubscribe-auth/ARJV6ITKUVFJQYNPHDDUZPTSKE3DXANCNFSM4SLEO6BQ .

[Holzhaus]

@Jiji98 can you elaborate what you have in mind? Are you proposing to display all sidebar items expanded?

I m not sure if this actually better, but feel free to experiment. Note that there is a search function, too.

[Jiji98]

Actually i took the example of "playing for an audience" (6.1.2). When using the search bar, a message " Your search did not match any document" is displayed. So I was actually thinking about displaying in the table of content all the various subtitles such that one opening the manual knows exactly where to go to for what he needs. Also I have not been able to download the manual in PDF form so I dont really know if this is just been displayed in my machine or everyone else got the same.

[Holzhaus]

Hmm, I don't think uncollapsing the whole sidebar is a good idea, because it would become far too long. However, maybe we can increase the :maxdepth: option in index.rst to 3 or 4.

[Jiji98]

:maxdepth:

I see

[Holzhaus]

Maybe we can improve the index further by using multiple toctrees with captions, e. g. :

.. toctree::
   :caption: Getting Started
   chapter/foo
   chapter/bar

.. toctree::
   :caption: Next Large section
   chapter/baz
   chapter/bla

[Jiji98]

The documentation is built with ReadTheDocs with Sphinx docs generator. Although the stuff is customizable, a certain pattern can’t be crossed. Since there is already a search bar in the manual. It will be better to work on improving the search functionality as it’s the simplest way for a user to get what they are looking for. I think a regex function can be created to find and match a word or phrase a user is looking for Also, the max depth is currently set at 2 so if I was to increase it to 3 or 4 it will include sub headings in the toctree. Changes can be made on the index.rst file but I looked for the the file in the installation folder and didn’t see it

[Holzhaus]

Using multiple toctrees on the index page, combined with toctree options and tuning the toctree depth would be an option though.

The search result scoring needs to be done in JavaScript, feel free to work on it. For example, all results in source/hardware/controllers should be weighted less then other results.

[Jiji98]

I have been documenting myself on the toctree function used in sphinx documentation but still the modifications are to be made on the ''index.rst'' file but I have issues locating this file I don't really know what to do I had in mind updating the depth several times until having an optimal result but...

[Holzhaus]

I have been documenting myself on the toctree function used in sphinx documentation but still the modifications are to be made on the ''index.rst'' file but I have issues locating this file

https://github.com/mixxxdj/manual/blob/manual-2.2.x/source/index.rst

[Jiji98]

Thank you!