Documentation Upgrade Working Group: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
|||
| Line 1: | Line 1: | ||
<!-- Documentation_Upgrade_Working_Group.mediawiki --> | |||
The purpose of this group is to address issues related to documenting blocks in a manner which uses source code of the blocks as the basis of all related documents. | The purpose of this group is to address issues related to documenting blocks in a manner which uses source code of the blocks as the basis of all related documents. | ||
| Line 15: | Line 16: | ||
=== Create new process / work flow to generate user-friendly block docs === | === Create new process / work flow to generate user-friendly block docs === | ||
== Some notes from #Docs chat == | |||
The "C++ API and Users Guide" will be a combination of programatically generated API docs and user-oriented information. | |||
The "C++ API and Users Guide" will contain: | |||
* | Summary description of the block | ||
* | Block parameters | ||
** | Port information | ||
** | Any relevant theoretical background on the block ** | ||
* | Example flowgraphs ** | ||
Block API documentation | |||
The wiki block docs will contain: | |||
Summary + | |||
Block parameters + | |||
Technical details | |||
Example flowgraphs | |||
Link to API docs | |||
* ** - From wiki | |||
* + - From code | |||
== Road map for group == | == Road map for group == | ||
What are the plans to move forward? | What are the plans to move forward? | ||
1. Create a list of all blocks from source code.<br> | |||
2. Create procedures, scripts, etc. to render the "C++ API and Users Guide"<br> | |||
3. Create bots to scan for changes in the source code.<br> | |||
4. Provide links to support editing the Wiki.<br> | |||
Revision as of 15:23, 19 September 2023
The purpose of this group is to address issues related to documenting blocks in a manner which uses source code of the blocks as the basis of all related documents.
Items to address
How will block docs be different between 3.x and 4.0?
Will all 4.0 blocks have a different API, or only those which use multiple processors?
Use of Doxygen / Sphinx / Wiki
Examine current process of generating the doxygen manual
The GNU Radio Manual and C++ API Reference document currently does not reflect the current release version.
Create new process / work flow to generate user-friendly block docs
Some notes from #Docs chat
The "C++ API and Users Guide" will be a combination of programatically generated API docs and user-oriented information. The "C++ API and Users Guide" will contain:
Summary description of the block Block parameters Port information Any relevant theoretical background on the block ** Example flowgraphs ** Block API documentation
The wiki block docs will contain:
Summary + Block parameters + Technical details Example flowgraphs Link to API docs
- ** - From wiki
- + - From code
Road map for group
What are the plans to move forward?
1. Create a list of all blocks from source code.
2. Create procedures, scripts, etc. to render the "C++ API and Users Guide"
3. Create bots to scan for changes in the source code.
4. Provide links to support editing the Wiki.