Documentation Upgrade Working Group: Difference between revisions

From GNU Radio
Jump to navigation Jump to search
 
(3 intermediate revisions by the same user not shown)
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 11: Line 12:
=== Examine current process of generating the doxygen manual ===
=== Examine current process of generating the doxygen manual ===


The [https://www.gnuradio.org/doc/doxygen/index.html GNU Radio Manual and C++ API Reference] document currently does not reflect the current release version.
The [https://www.gnuradio.org/doc/doxygen/index.html GNU Radio Manual and C++ API Reference] document currently requires a manual update to the gnuradio.org website. Automating the process would keep the document on the website up to date with the latest release.


=== Create new process / work flow to generate user-friendly block docs ===
=== Create new process / work flow to generate user-friendly block docs ===


Current Wiki Block docs have the following sections:
== Some notes from #Docs chat ==


* A functional description
The "C++ API and Users Guide" will be a combination of programatically generated API docs and user-oriented information.
* Parameters
The "C++ API and Users Guide" will contain:
* An example flowgraph
    Summary description of the block
* Links to the source code
    Block parameters
** C++ or Python
    Port information
** Include files
    Any relevant theoretical background on the block **
** YML file
    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?
We need to schedule a video meeting to discuss the following items:
 
# Determine if code-related docs should be in one (unified) or two formats, e.g. Wiki block docs and Doxygen docs.
# Assess usefulness of Doxygen docs.
#* The published "C++ API and Users Guide" went for over two years without being updated. (v3.9.4.0 to v3.10.9.1).
#* Developers and others who build GR from source have their own current "C++ API and Users Guide" in `~/gnuradio/build/docs/doxygen/html/index.html`
# Create standardized formats for Wiki block docs and Doxygen docs.
# Require adequate 'documentation' sections in header files and YML files for new blocks before merging.

Latest revision as of 15:32, 3 February 2024

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 requires a manual update to the gnuradio.org website. Automating the process would keep the document on the website up to date with the latest release.

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

We need to schedule a video meeting to discuss the following items:

  1. Determine if code-related docs should be in one (unified) or two formats, e.g. Wiki block docs and Doxygen docs.
  2. Assess usefulness of Doxygen docs.
    • The published "C++ API and Users Guide" went for over two years without being updated. (v3.9.4.0 to v3.10.9.1).
    • Developers and others who build GR from source have their own current "C++ API and Users Guide" in `~/gnuradio/build/docs/doxygen/html/index.html`
  3. Create standardized formats for Wiki block docs and Doxygen docs.
  4. Require adequate 'documentation' sections in header files and YML files for new blocks before merging.