search

cherrypy / cheroot

Cheroot is the high-performance, pure-Python HTTP server used by CherryPy. Docs -->
https://cheroot.cherrypy.dev
BSD 3-Clause "New" or "Revised" License
184 stars 90 forks source link

Visualize the project structure #115

Open webknjaz opened 6 years ago

webknjaz commented 6 years ago

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 ...

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 commented 5 years ago

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

serhii73 commented 1 year ago

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

webknjaz commented 1 year ago

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 commented 1 year ago

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.