Skip to content
New issue

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

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

Already on GitHub? # 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 <qlyoung@qlyoung.net>
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
# for free to join this conversation on GitHub. Already have an account? # to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants