Documentation re-org 2018: Difference between revisions
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: | ||
=== Issues to work out as part of this re-org === | |||
# Usage manual may be hard to find for new people, and has been getting almost zero updates/refinements | |||
# In general, people are not editing gnuradios documentation, so perhaps we need to make it even easier to edit? | |||
# 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]] | |||
# 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 | |||
=== Current State === | |||
GNU Radio documentation lives in one of the following places: | |||
# 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 | |||
the | === Big Question === | ||
Whether we want to use doxygen or the wiki for the non-block-specific documentation | |||
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
- Usage manual may be hard to find for new people, and has been getting almost zero updates/refinements
- In general, people are not editing gnuradios documentation, so perhaps we need to make it even easier to edit?
- 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
- 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
Current State
GNU Radio documentation lives in one of the following places:
- 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 here, not much in it though
- Wiki
Big Question
Whether we want to use doxygen or the wiki for the non-block-specific documentation
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