search

useblocks / sphinx-needs-enterprise

Sphinx-Needs Functions for enterprise users
http://useblocks.com/sphinx-needs-enterprise/
Other
5 stars 0 forks source link

Support for enterprise sphinx theme #10

Open twodrops opened 2 years ago

twodrops commented 2 years ago

Although there are several sphinx themes, most of them are not suitable for enterprise world or are not well maintained anymore. Alabaster is too plain and Read the docs is very popular, but not good with maintenance (57 open PRs as on 08.11.2021).

Need a new professional theme which could be a fork of any existing one, but more suitable and maintainable for the enterprise world. The theme could be completely neutral to sphinx-needs but shall play well with all sphinx-needs layouts (need data-table etc.)

danwos commented 2 years ago

As you already know, I like this idea. And I agree that it should be Sphinx-Needs independent.

Maybe we can collect here some requirements, so that it becomes clear what is missing in current sphinx themes.

Requirements / Features

Technical / Interaction

  1. Must play well with any kind of Sphinx extension (Respect their css and js)
  2. Table handling must be smart enough for small and huge data tables (maybe a fullscreen-mode for huge tables can be provided.)
  3. Shall be 100% responsive (incl. tables)

Data

  1. Shall be able to show extra links somewhere (e.g. to an internal company service)
  2. Extra Links shall be configurable per page/folder (E.g. pages for Team A shows link to JIRA project A, pages for team B ... you got the idea :) )

Hint: The above req 1+2 can be done via html_sidebars, which take a list of html-templates for each page/folder.

  1. However, the theme must handle complex, long sidebars. Maybe support multiple html_sidebars like config elements (left, right, header, footer).

  2. Shall provide sidebars for:

    • Documentation Chapter menu
    • Page content menu
    • Page Meta data (e.g. responsible person)
    • Git data (last change, last contributor, history of changes, ...)
    • Extra links
    • Sphinx-Needs stats (e.g. amount of req-needs on all sub-pages)

Other features

I'm not 100% sure, if a complete own theme is needed to get the above done, or a an existing theme plus 2-3 smaller sphinx-extensions would be enough.

But interesting topic :)

danwos commented 2 years ago

Maybe we should not simply provide another, static theme, but more a dynamic theme via react.

So would have a lot of benefits and allows a lot of dynamic function and maybe also auth.

So instead of a theme, we provide a new builder "react", which creates a single "index.html" file and js-files (which contains the app). The documentation content itself can then be any format, which can be loaded by react. For this the already existing "json" builder looks promising.

Here is an article, which describes some steps of how it can be done: https://medium.com/@mtiller/rendering-sphinx-documentation-with-react-95b785293a76

danwos commented 2 years ago

This React-App could also care about the "moved url problem" from https://github.com/useblocks/sphinxcontrib-needs/issues/390