Visualize the project structure

[webknjaz]

Let's integrate https://sdras.github.io/project-explorer-site/ (https://github.com/sdras/project-explorer by @sdras) in docs.

This project nicely visualizes the directory tree structure, which is useful as an explanation of what's inside.

(Demo: https://sdras.github.io/vue-directory-tree/)

I'm submitting a ...

• bug report
• feature request
• question about the decisions made in the repository

Is your feature request related to a problem? Please describe.

Currently, there's no public explanation of the things present in this repository.

Describe the solution you'd like

I was a potential contributor, I would like that when I browse https://cheroot.cherrypy.dev I can find an explanation of the whole project structure.

Describe alternatives you've considered

N/A

Additional context

https://twitter.com/sarah_edo/status/1039167305245048833

[webknjaz]

@serhii73 you could try doing this but keep in mind that it'd require integrating some JS tooling.

[serhii73]

I'm on it, @webknjaz. Feel free to assign this issue to me.

[webknjaz]

So I think that on the Sphinx side, you'll need to make a dedicated template inheriting https://github.com/pradyunsg/furo/blob/main/src/furo/theme/furo/page.html with something like {% extends "!project-explorer-template.html" if meta is mapping and meta.get("use-project-explorer-template") else "!page.html" %} or maybe have a similar conditional futher in the template that would redefine the content block. And in the RST document, you'd just make use of the corresponding custom meta field per https://www.sphinx-doc.org/en/master/development/theming.html#use-custom-page-metadata-in-html-templates / https://www.sphinx-doc.org/en/master/development/templating.html#meta / https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html#metadata.
This part can be implemented first, with some dummy static content put into the template.

The dynamic content injected would need to be generated via NodeJS (https://pypi.org/project/nodeenv/) in the first prototype, but it'd best to try to generate those files from Python. Maybe there would be some static JS + some data generated from a dedicated (YAML?) config with descriptions for some folders/files, and injected into those JS files. That's something to explore. OTOH, having a mechanism to grab VueJS and other possible deps could be necessary, so I'm not sure if it makes sense to try to get rid of NodeJS. You can also look into https://github.com/amol-/dukpy for this.
The generation of this JS tree would need to be bound to one of the Sphinx extension hooks (https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events).

[serhii73]

I'm sorry, I've been doing many things lately and don't have time to deal with this issue. I hope someone will be happy to do this task. Thanks for everything, @webknjaz.