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: improve table-of-contents organization #16297

Merged
merged 1 commit into from
Jun 27, 2024

Conversation

qlyoung
Copy link
Member

@qlyoung qlyoung commented Jun 25, 2024

The current TOC organization is not really following Sphinx best practices and is resulting in a jumble of articles showing up in the sidebar.

Result of these changes is viewable here: https://qlyoung.net/frr-docs/
Compare to: https://docs.frrouting.org/en/latest/

This change primarily organizes existing articles into three major sections:

  • Introduction
    • Contains system requirements, architecture & design, installation, basic setup
  • Basics
    • Covers basic commands, concepts, and some random things that don't fit elsewhere
  • Protocols
    • Contains all protocol documentation, and other miscellaneous daemon docs such as those on Zebra, watchfrr, mgmtd, etc.

The appendix has been left as is, but the TOC now has a caption which has the effect of adding a section separator in the nav sidebar.

In order to make the new structure make sense:

  • Some content has been lifted up from the "Overview" page into the index page
  • Most content has been pushed down from the "Overview" page into the "About" page (new)
  • BFD's page is now titled "BFD" for consistencty; it was the only one that had the full protocol name written out in the title

And a couple drivebys:

  • BFD's intro description paragraph was rewritten to make more sense
  • Old language stating that we publish platform packages on the Github releases page was removed
  • References to source building instructions were consolidated into that section

The current TOC organization is not really following Sphinx best
practices and is resulting in a jumble of articles showing up in the
sidebar.

This change primarily organizes existing articles into three major
sections:

* Introduction
  - Contains system requirements, architecture & design, installation,
    basic setup
* Basics
  - Covers basic commands, concepts, and some random things that don't
    fit elsewhere
* Protocols
  - Contains all protocol documentation, and other miscellaneous daemon
    docs such as those on Zebra, watchfrr, mgmtd, etc.

The appendix has been left as is, but the TOC now has a caption which
has the effect of adding a section separator in the nav sidebar.

In order to make the new structure make sense:

* Some content has been lifted up from the "Overview" page into the
  index page
* Most content has been pushed down from the "Overview" page into the
  "About" page (new)
* BFD's page is now titled "BFD" for consistencty; it was the only one
  that had the full protocol name written out in the title

And a couple drivebys:
* BFD's intro description paragraph was rewritten to make more sense
* Old language stating that we publish platform packages on the Github
  releases page was removed
* References to source building instructions were consolidated into that
  section

Signed-off-by: Quentin Young <[email protected]>
Copy link
Member

@riw777 riw777 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks good

@qlyoung
Copy link
Member Author

qlyoung commented Jun 27, 2024

ci:rerun

Copy link
Member

@ton31337 ton31337 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@choppsv1 choppsv1 merged commit a300c8e into FRRouting:master Jun 27, 2024
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants