Documentation re-org 2018

Plan

Split up effort into two stages:

1. First, organize the non-block-specific docs (stuff that is not specific to a block/class/function)
2. Second, "fill out" and improve presentation of block-specific docs within doxygen

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

Problems

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.
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).

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

Proposed Solution if we want to convert to using the 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
2. We can make the old doxygen usage manual redirect to the wiki, so people use to using it (or who have bookmarked it) will not be disturbed
3. For people who have to work offline- the old doxygen usage manual can also explain how the important wiki pages are exported and live in the gnuradio git repo, see Exporting Usage Manual
4. Rename "GNU Radio Manual and C++ API Reference" to "GNU Radio C++ API Reference" and try to remove links to the old usage manual. What is left will be simply a list of blocks/functions/classes and not be tutorial in nature.
5. Somehow fold the Python Manual/API into the main Doxygen one, since there is just so little information in the Python API other than a list of the Python versions of every function/class
6. The wiki itself needs a re-org, or at least a minor clean up. Perhaps categorize pages into documentation/tutorials/news/events/archives
7. 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.

Notes on Usage Manual Conversion

1. Build Instructions and Information -should be its own section
2. Exploring GNU Radio -this is just two examples, needs to be folded into examples section
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 -duplicate info, should be folded into other sections
14. Polyphase Filterbanks -very block specific, should be in doc-strings
15. OFDM -more of a tutorial, should be folded into tutorial section
16. Packet Data Transmission -not sure about this one, can likely be folded into other sections
17. Out-of-Tree Configuration -needs updating and moved to section about creating custom OOT module
18. Instructions for using VOLK in GNU Radio -CONVERTED