Skip to content

Improving documentation presentation and improve organization of Sphinx documentation

Here is a proposal of changes to improve the navigation and organization of the Model Library (Sphynx documentation). Most of these changes refer to how the information is presented in the Web model library.

  • Remove the number of the chapter (Module section) but keep the numbering in Section and subsections. 1

  • Redesign some documentation to avoid as much as possible more than 2 levels of subsections. For example: avoid situations like these:

1. Module Name

1.1 Module Description

1.1.1 Design

1.1.1.1 First real section in doc

(Few exceptions apply such as in modules that truly require this subsubsection, e.g. Wifi, Lte)

  • Break the content of the modules into more sections (some free form, some required) instead of saturating all the content inside 2 sections. For instance, most of the documentation on each module is contained inside 2 sections:Module description and Usage

  • Clear definition of some sections that are free form and some that should always exist (permanent sections) in the module and in the same order. This contributes to a unified feel among all the documentation and makes it easier to navigate if you know what is the expected order on each module.

  • Avoid subsections of just 1 paragraph. They are unnecessary and make the documentation harder to read by creating more levels. Exceptions include the "permanent sections".

  • (WEB presentation) If possible add spaces on each level of subsection (indentation). If this is not possible, different font color, size and type for the Module, Section and subsections should be enough.

This image summarizes this proposal:

ns3docfeel

Edit: Scope and limitations have been brought to the top Section.

Additional Recommendations:

  • (WEB presentation) Make the Table of Contents on the left not scroll with the rest of the documentation to make it always visible

  • Break the documentation of some modules into their own chapter.

Following this proposal, format changes have been made to these modules:

Edited by Alberto Gallegos