Documentation re-org 2018: Difference between revisions

From GNU Radio
Jump to navigation Jump to search
(first shot at a plan)
 
No edit summary
 
(51 intermediate revisions by the same user not shown)
Line 1: Line 1:
Currently, GNU Radio documentation lives in one of the following places:
=== Issues to work out as part of this re-org ===


1. Usage Manual in Doxygen (18 pages that cover various topics across GR)
# Usage manual may be hard to find for new people, and has been getting almost zero updates/refinements
2. "Components" descriptions in Doxygen (various length blurbs about each category of GNU Radio blocks)
# In general, people are not editing gnuradios documentation, so perhaps we need to make it even easier to edit?
3. Doxygen strings for each block, describing arguments and such (this info lives in the same files as the code for the block)
# Should we just move the usage manual to the wiki so that the doxygen manual is only block-specific stuff?  What about people who need to work offline?  see [[Exporting Usage Manual]]
4. Wiki
# When you go to https://gnuradio.org/doc/doxygen/ the organization may be confusing for new people, and several of the drop downs don't have useful info.  The wiki home page attempts to provide guidance.
# We don't define what type of information goes where.  E.g., if someone new-ish wants to get more info about something (e.g. PMTs), it's not clear whether to use the wiki or usage manual.
# Some information is duplicated across the wiki and usage manual (e.g. the wiki's BlocksCodingGuide is like a condensed version of several usage manaul sections).
# The wiki itself needs a re-org, or at least a minor clean up. Perhaps categorize pages into documentation/tutorials/news/events/archives
# The python manual contains almost no useful info.  If its only purpose is going to be a list of python version's of functions, blocks, then there is probably a better way to present that info


Problems:
=== Current State ===


1. When you go to https://gnuradio.org/doc/doxygen/ the organization may be confusing for new people, and several of the drop downs don't have useful info.  The wiki home page attempts to provide guidance.
GNU Radio documentation lives in one of the following places:
2. We don't define what type of information goes where.  E.g., if someone new-ish wants to get more info about something (e.g. PMTs), it's not clear whether to use the wiki or usage manual.
3. Some information is duplicated across the wiki and usage manual (e.g. the wiki's BlocksCodingGuide is like a condensed version of several usage manaul sections).


Proposed Solution:
# Usage Manual in Doxygen (18 pages that cover various topics across GR)
# "Components" descriptions in Doxygen (various length blurbs about each category of GNU Radio blocks)
# Doxygen strings for each block, describing arguments and such (this info lives in the same files as the code for the block)
# Python (Sphinx) manual [https://www.gnuradio.org/doc/sphinx/ here], not much in it though
# Wiki


1. One by one, migrate the information in the usage manual sections and components sections to the wiki, removing any redundancies in  
 
the process.  On the home page of the wiki, we will link to pages in the wiki instead of pages in the Doxygen usage manual
=== Big Question ===
2. We can make the doxygen usage manual redirect to the wiki, so people use to using it (or who have bookmarked it) will not be disturbed
 
3. Rename "GNU Radio Manual and C++ API Reference" to "GNU Radio C++ API Reference" and try to remove links to the old usage manual
Whether we want to use doxygen or the wiki for the non-block-specific documentation
4. The wiki itself needs a re-org, or at least a minor clean up.  Perhaps categorize pages into documentation/tutorials/news/events/archives
 
5. Figure out how new people registering for the wiki can actually be granted access quickly. One idea- add a field to the registration process asking for a quick blurb about how they use GNU Radio, and when someone registers it should email someone who can quickly see that it's not a bot, and verify the registration.
Arguments for using the wiki:
 
# We have a wiki, non-veteran people may assume that it is the primary source for how-to's and such
# Wiki has more tools suited for this type of non-block-specific documentation
# Quicker to make a change, changes immediately show up (changes to the doxygen require a git fork/PR and don't show up for months)
# Searching (through Google or the wiki itself) works a little better than searching for something in doxygen
 
Arguments for using doxygen:
 
# You can click functions/blocks/class names and it links to the corresponding page of the API
# People using an older version of GNU Radio can get the corresponding older version of the usage manual (argument countered if we use [[Exporting Usage Manual]])
# Changes are through git so they are very much backed up, backing up the wiki is more manual
 
=== Notes on useful info in sphinx ===
 
* A majority of it is just the python names of all the blocks
* The Runtime category has some important stuff, although right now it's not split up in terms of whether you would call the function from within a block or not
* There's only a handful of helper classes, they can all be lumped into one category
 
 
 
=== Notes on Usage Manual Conversion ===
# Build Instructions and Information '''-I went through and copied info that didn't exist elsewhere to BuildGuide'''
# Exploring GNU Radio '''-contains two tutorials that are super short and don't add anything more to what is already in the guided tutorials'''
# Handling flow graphs '''-CONVERTED'''
# Polymorphic Types '''-CONVERTED'''
# Metadata Information '''-CONVERTED'''
# Message Passing '''-CONVERTED'''
# Stream Tags '''-CONVERTED'''
# Tagged Stream Blocks '''-CONVERTED'''
# Logging '''-CONVERTED'''
# Performance Counters '''-CONVERTED'''
# Block Thread Affinity and Priority '''-CONVERTED'''
# Configuration files '''-CONVERTED'''
# Python Blocks '''-I folded the material into the other manual sections (wiki version only)'''
# Polyphase Filterbanks '''-extracted info into a new manual page on using PFBs'''
# OFDM '''-converted it to wiki and now its listed under tutorials'''
# Packet Data Transmission '''-essentially a tutorial on how to use an obscure set of blocks, not sure if its even worth carrying over'''
# Out-of-Tree Configuration '''-everything here is covered in the OutOfTreeModules page, granted that page needs to be organized'''
# Instructions for using VOLK in GNU Radio '''-CONVERTED'''

Latest revision as of 21:45, 3 November 2018

Issues to work out as part of this re-org

  1. Usage manual may be hard to find for new people, and has been getting almost zero updates/refinements
  2. In general, people are not editing gnuradios documentation, so perhaps we need to make it even easier to edit?
  3. Should we just move the usage manual to the wiki so that the doxygen manual is only block-specific stuff? What about people who need to work offline? see Exporting Usage Manual
  4. When you go to https://gnuradio.org/doc/doxygen/ the organization may be confusing for new people, and several of the drop downs don't have useful info. The wiki home page attempts to provide guidance.
  5. We don't define what type of information goes where. E.g., if someone new-ish wants to get more info about something (e.g. PMTs), it's not clear whether to use the wiki or usage manual.
  6. Some information is duplicated across the wiki and usage manual (e.g. the wiki's BlocksCodingGuide is like a condensed version of several usage manaul sections).
  7. The wiki itself needs a re-org, or at least a minor clean up. Perhaps categorize pages into documentation/tutorials/news/events/archives
  8. The python manual contains almost no useful info. If its only purpose is going to be a list of python version's of functions, blocks, then there is probably a better way to present that info

Current State

GNU Radio documentation lives in one of the following places:

  1. Usage Manual in Doxygen (18 pages that cover various topics across GR)
  2. "Components" descriptions in Doxygen (various length blurbs about each category of GNU Radio blocks)
  3. Doxygen strings for each block, describing arguments and such (this info lives in the same files as the code for the block)
  4. Python (Sphinx) manual here, not much in it though
  5. Wiki


Big Question

Whether we want to use doxygen or the wiki for the non-block-specific documentation

Arguments for using the wiki:

  1. We have a wiki, non-veteran people may assume that it is the primary source for how-to's and such
  2. Wiki has more tools suited for this type of non-block-specific documentation
  3. Quicker to make a change, changes immediately show up (changes to the doxygen require a git fork/PR and don't show up for months)
  4. Searching (through Google or the wiki itself) works a little better than searching for something in doxygen

Arguments for using doxygen:

  1. You can click functions/blocks/class names and it links to the corresponding page of the API
  2. People using an older version of GNU Radio can get the corresponding older version of the usage manual (argument countered if we use Exporting Usage Manual)
  3. Changes are through git so they are very much backed up, backing up the wiki is more manual

Notes on useful info in sphinx

  • A majority of it is just the python names of all the blocks
  • The Runtime category has some important stuff, although right now it's not split up in terms of whether you would call the function from within a block or not
  • There's only a handful of helper classes, they can all be lumped into one category


Notes on Usage Manual Conversion

  1. Build Instructions and Information -I went through and copied info that didn't exist elsewhere to BuildGuide
  2. Exploring GNU Radio -contains two tutorials that are super short and don't add anything more to what is already in the guided tutorials
  3. Handling flow graphs -CONVERTED
  4. Polymorphic Types -CONVERTED
  5. Metadata Information -CONVERTED
  6. Message Passing -CONVERTED
  7. Stream Tags -CONVERTED
  8. Tagged Stream Blocks -CONVERTED
  9. Logging -CONVERTED
  10. Performance Counters -CONVERTED
  11. Block Thread Affinity and Priority -CONVERTED
  12. Configuration files -CONVERTED
  13. Python Blocks -I folded the material into the other manual sections (wiki version only)
  14. Polyphase Filterbanks -extracted info into a new manual page on using PFBs
  15. OFDM -converted it to wiki and now its listed under tutorials
  16. Packet Data Transmission -essentially a tutorial on how to use an obscure set of blocks, not sure if its even worth carrying over
  17. Out-of-Tree Configuration -everything here is covered in the OutOfTreeModules page, granted that page needs to be organized
  18. Instructions for using VOLK in GNU Radio -CONVERTED
Retrieved from "https://wiki.gnuradio.org/index.php?title=Documentation_re-org_2018&oldid=4523"