Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support for enterprise sphinx theme #10

Open
twodrops opened this issue Nov 8, 2021 · 3 comments
Open

Support for enterprise sphinx theme #10

twodrops opened this issue Nov 8, 2021 · 3 comments

Comments

@twodrops
Copy link

twodrops commented Nov 8, 2021

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
Copy link
Member

danwos commented Nov 8, 2021

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

  • Shall provide a day/dark mode (see Furo theme)
  • Colors shall be easily configurable
  • Sticky headers and footers (configurable)
  • Collapsible sidebars, to gain more "width" for huge tables or wide pictures

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
Copy link
Member

danwos commented Jan 6, 2022

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
Copy link
Member

danwos commented Jan 10, 2022

This React-App could also care about the "moved url problem" from useblocks/sphinx-needs#390

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants