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

DOC - Extensions documentation structure needs improvement #1727

Open
trallard opened this issue Feb 23, 2024 · 2 comments
Open

DOC - Extensions documentation structure needs improvement #1727

trallard opened this issue Feb 23, 2024 · 2 comments
Assignees
Labels
kind: documentation Improvements or additions to documentation

Comments

@trallard
Copy link
Collaborator

trallard commented Feb 23, 2024

Updating this page in the docs made me realize that this part of the docs could really use a restructure:

  • This page is titled Sphinx Design but it also includes info about two other Sphinx extensions, sphinx-copybutton and sphinx-togglebutton, that have nothing to do with sphinx-design.
  • More confusingly, the next page in the docs, "Extending the theme" has a section about sphinx-togglebutton, as if that extension wasn't just discussed on the previous page.
  • This page is under: "User Guide / Content and features." The "Content and features" section has four pages, three of which are about other extensions that our theme is designed to work with. This makes me think that we should probably have a dedicated section on such extensions. And each page in that section should be dedicated to that particular extension (even if it means that some of those pages will be really short).

Originally posted by @gabalafou in #1721 (comment)

Note

Opening this issue so we can discuss this organisation proposal as a team @drammock @12rambau @choldgraf and then @gabalafou and I can work on any changes

@trallard trallard added the kind: documentation Improvements or additions to documentation label Feb 23, 2024
@trallard trallard self-assigned this Feb 23, 2024
@drammock
Copy link
Collaborator

I like the proposed restructuring. I'd recently noticed the same issue with the "sphinx design" page (but I failed to open an issue about it and promptly forgot). So I'm glad you noticed too and said something.

@choldgraf
Copy link
Collaborator

That makes sense to me as well - sounds like this is content that had grown organically and is now in need of some pruning and restructuring. I also think it's helpful to have one page per extension because then there is a source of truth to go to when trying to figure out if the theme is behaving "as expected" since it's often hard to test for theme-specific CSS without just looking at its effects for reference.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
kind: documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

3 participants