F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Update model documentation guidelines and create-model.py script

Browse Source
This commit is contained in:
Alberto Gallegos Ramonet
2025-04-11 14:56:48 +09:00
committed by Tom Henderson
parent b0ad23b318
commit 11ae5e4cad
3 changed files with 195 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
utils/create-module.py
View File

@@ -230,103 +230,105 @@ static {CAPITALIZED}TestSuite s{COMPOUND}TestSuite;
DOC_RST_TEMPLATE = """Example Module Documentation
----------------------------
============================
.. include:: replace.txt
.. highlight:: cpp
.. heading hierarchy:
------------- Chapter
************* Section (#.#)
============= Subsection (#.#.#)
############# Paragraph (no number)
============= Module Name
------------- Section (#.#)
~~~~~~~~~~~~~ Subsection (#.#.#)
This is a suggested outline for adding new module documentation to |ns3|.
See ``src/click/doc/click.rst`` for an example.
This is the outline for adding new module documentation to |ns3|.
See ``src/lr-wpan/doc/lr-wpan.rst`` for an example.
The introductory paragraph is for describing what this code is trying to
model.
This first part is for describing what the model is trying to
accomplish. General descriptions and design, overview of the project
goes in this part without the need of any subsections. A visual summary
is also recommended.
For consistency (italicized formatting), please use |ns3| to refer to
ns-3 in the documentation (and likewise, |ns2| for ns-2). These macros
are defined in the file ``replace.txt``.
Model Description
*****************
Detailed |ns3| Sphinx documentation guidelines can be found `here <https://www.nsnam.org/docs/contributing/html/models.html>`_
The source code for the new module lives in the directory ``{MODULE_DIR}``.
Add here a basic description of what is being modeled.
Design
======
Briefly describe the software design of the model and how it fits into
the existing ns-3 architecture.
Scope and Limitations
=====================
---------------------
What can the model do? What can it not do? Please use this section to
describe the scope and limitations of the model.
This is should be your first section. Please use it to list the scope and
limitations. What can the model do? What can it not do? Be brief and concise.
References
==========
Section A
---------
Add academic citations here, such as if you published a paper on this
model, or if readers should read a particular specification or other work.
Free form. Your second section of your documentation and its subsections goes here.
The documentation can contain any number of sections but be careful to not use
more than two levels in subsections.
Section B
---------
Free form. The last section of your documentation with content goes here.
Usage
*****
-----
This section is principally concerned with the usage of your model, using
the public API. Focus first on most common usage patterns, then go
into more advanced topics.
Building New Module
===================
Include this subsection only if there are special build instructions or
platform limitations.
A brief description of the module usage goes here. This section must be present.
Helpers
=======
~~~~~~~
What helper API will users typically use? Describe it here.
A subsection with a description of the helpers used by the model goes here. Snippets of code are
preferable when describing the helpers usage. This subsection must be present.
If the model CANNOT provide helpers write "Not applicable".
Attributes
==========
~~~~~~~~~~
What classes hold attributes, and what are the key ones worth mentioning?
A subsection with a list of attributes used by the module, each attribute should include a small
description. This subsection must be present.
If the model CANNOT provide attributes write "Not applicable".
Output
======
Traces
~~~~~~
What kind of data does the model generate? What are the key trace
sources? What kind of logging output can be enabled?
A subsection with a list of the source traces used by the module, each trace should include a small
description. This subsection must be present.
If the model CANNOT provide traces write "Not applicable".
Advanced Usage
==============
Examples and Tests
------------------
Go into further details (such as using the API outside of the helpers)
in additional sections, as needed.
Examples
========
What examples using this new code are available? Describe them here.
Troubleshooting
===============
Add any tips for avoiding pitfalls, etc.
A brief description of each example and test present in the model must be here.
Include both the name of the example file and a brief description of the example.
This section must be present.
Validation
**********
----------
Describe how the model has been tested/validated. What tests run in the
test suite? How much API and code is covered by the tests? Again,
references to outside published work may help here.
test suite? How much API and code is covered by the tests?
This section must be present. Write ``No formal validation has been made`` if your
model do not contain validations.
References
----------
The reference material used in the construction of the model.
This section must be the last section and must be present.
Use numbers for the index not names when listing the references. When possible, include the link of the referenced material.
Example:
[`1 <https://ieeexplore.ieee.org/document/6012487>`_] IEEE Standard for Local and metropolitan area networks--Part 15.4: Low-Rate Wireless Personal Area Networks (LR-WPANs)," in IEEE Std 802.15.4-2011 (Revision of IEEE Std 802.15.4-2006) , vol., no., pp.1-314, 5 Sept. 2011, doi: 10.1109/IEEESTD.2011.6012487.
"""