Improve Documentation by having list of topics fixed on the left and table of contents on the right

[lokesh1729]

Hey all,

I am using Django for a long time. One thing I feel we can improve is that the reading experience of the documentation. Especially when the page is very long. Two problems I can see

1. There is a table of contents on the right side, but it is not fixed and it doesn't follow the page. So, when the page is very long, keeping track of the topic is very very hard and it takes a mental leap to go back and navigate.
2. Also, on any page, you can only see only the previous topic and the next topic, not the whole content.

Below are some of the example documentation

https://getbootstrap.com/docs/5.1/getting-started/introduction/

https://vuejs.org/v2/guide/

https://docs.spring.io/spring-framework/docs/current/reference/html/core.html

https://tailwindcss.com/docs/configuration

I have done a search on the issues and found #239 is closed and #494 is still open from 2015. I am not blaming anyone honestly, I know being an open-source project, it is hard to prioritize things. I wanted to take the initiative and work on it.

I think the problem here is we need to migrate entirely from sphinx documentation, but unfortunately in the python community, there's no better alternative. Please suggest or point me in the direction of how can we achieve this.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[CuriousLearner]

This is not stale. I think a discussion is needed before closing this issue (if that is the choice made).

[Charan-Deep]

I want to work on this issue. Please Assign me

[priyanshuyadav28]

We can create a grid with four columns three for the left part and one for the right part with little more width compared to the left part. In that way the left side content which is going so down will come in a single page with the same height as of the right part .

[MaazAlam39]

First of all we have to choose a documentation tool such as Microsoft Word, Google Docs or specialized tools like reading the docs. Create a list of topics: Make a list of all the topics you want to cover in your documentation.

Organize the topics in a logical order that makes sense for your readers. For example, you might want to start with an introduction, followed by the main body of the documentation, and end with a conclusion or a reference section.

Create a table of contents: Once you have organized your topics, create a table of contents that lists all the topics and their corresponding page numbers.

Link the table of contents

Add headings & Update as needed.

[kaushal-malpure]

@pauloxnet @lokesh1729 @CuriousLearner We can simply expand the contents of heading after clicking on it, so that it will help decreasing length of the table of content to the right bar. So it will make easier to track the table of contents.

[k-s-dev]

I was struggling with the similar issues, have a quick fix that works locally for me.

The issue is related to multiple issues and toc being the important part of documentation, so problem statement can be structured

• managing the content of toc
• implementation
  • identify and finalize required features
  • identify solutions that work across formats (html, pdf, ...) and devices (desktop, mobile, ...)

I am proposing solutions for implementation for html.

Latex/pdf format seems to have the required features already.

Solutions

• quick easy fix for personal (local) use
• long term change in django docs website
  • use an existing sphinx-theme and modify it
  • create css and js solution in current theme
  • move to Quarto: An open-source scientific and technical publishing system

Quick easy fix for personal usage

Sphinx-themes already have many themes for html which provides most of the required features discussed.

Build the documentation as suggested in Django Docs's related section.

Make the following changes before using the final build command.

• install and configure theme: furo: quickstart
• build
• use the locally built docs

Long term solution

• use an existing sphinx-theme and modify it
• create css and js solution in current theme
• move to Quarto: An open-source scientific and technical publishing system
  • based on quarto markdown text files
  • gives much more features than sphinx, for example
  • mermaid diagrams
  • code execution with results helpful in adding tables and diagrams
  • structure the documentation in more evolved book format

First 2 options are relatively easier.

For Quarto, if there is any traction on toc related issues and quarto is in consideration, I could share some more ideas. There will be more effort required, but not as much as it may seem.

I have already done some work to automate converting rst format files to qmd (quarto markdown).