Reorganize algorithm docs

[dblalock]

Our docs currently have 1) a lot of redundancy, 2) a difficult interface for finding much or most of our API surface area. This creates both confusion for readers and engineering burden for maintainers.

Specific problems/challenges:

• We write independent overviews of each algorithm in three different places. This increases the barrier to contributing new algorithms and makes maintenance more difficult. E.g., for BlurPool:
  • Place 1: composer.algorithms.blurpool docstring
  • Place 2: BlurPool method card
  • Place 3: composer.algorithms.blurpool.BlurPool algorithm class (for most algos)
• Several algorithms have different interfaces. These interfaces show up in different places in the docs, and only some interfaces are available without clicking through several levels of API reference. As an example, blurpool has:
  • BlurPool the Algorithm, documented in:
    • composer.algorithms API reference
    • composer.algorithms.blurpool API reference
    • composer.algorithms.blurpool.blurpool API reference
  • apply_blurpool the all-in-one model surgery function
    • composer.algorithms.blurpool API reference
    • composer.algorithms.blurpool.blurpool API reference
  • BlurConv2d and company, documented in
    • composer.algorithms.blurpool API reference
    • composer.algorithms.blurpool.blurpool_layers API reference
  • blur_pool2d and other standalone functions for the core logic, documented in
    • composer.algorithms.blurpool API reference
    • composer.algorithms.blurpool.blurpool API reference
• Because we take up so much sidebar real estate with method cards and model cards, any API not documented in one of these pages is really hard to find; I have to click on "API reference" at the very bottom (not even visible unless I scroll down a lot), and then repeatedly expand submodules and scroll down to find stuff.
  • E.g., it's super annoying to find our functional API right now, even if you know where to look.
• Searching, especially for algorithms, is hard because we have so many pages with similar names and content. Which makes the recursive "API reference" clicking more mandatory.

Proposal

Algorithms

• Prefix every algorithm directory with an underscore. E.g., composer.algorithms._blurpool
  • This will eliminate redundant documentation of algorithm contents. Everything that should be visible under composer.algorithms will now only be visible under composer.algorithms. Same for composer.functional.
• Make a top level composer.layers in which nn.modules like BlurConv2d can be discovered without digging several layers deep in the API reference.
• Add standalone logic like blur_pool2d to composer.functional (or maybe elsewhere?)
• Make method cards README.rst files instead of README.md, and have algorithm module-level docstrings just .. include:: these files.
  • Eliminates duplicate descriptions
  • Makes it much easier for other algorithm code to reference the method card (instead of hardcoding a URL in our last-released docs that may have out of sync content and/or break at any time). This also allows eliminating duplicate descriptions in Algorithm class docstrings.
• Have method cards link to, but not include, docstrings for all interfaces for a given algorithm.
  • If I want to use BlurPool but am not sure of the best way to use it in my codebase, I should be able to click on the big "BlurPool" heading and see my options.
  • But if we add the full docstrings to the method card, it's a giant wall of mostly-redundant text (and it duplicates the docstrings being shown elsewhere, like in composer.functional).
  • Right now there no links to the actual code, so you're stuck using the search bar if you want to deviate from the simple examples shown.
• Eliminate the "Methods Overview" page. It looks cool but is redundant with the sidebar. Or maybe add its content to the bottom of one of the quickstart/overview pages.

Models

• Similarly make model cards be the module-level docstrings under composer.modules

Sphinx

• Minor: Make our current toctree collapsible. I should be able to minimize the Method Cards, Trainer section, etc, like in the PyTorch and PyTorch Lightning docs.
• Minor bugfix: make expanding sections in the API reference not reload the page. Right now I have to scroll to bottom from very top, click "API reference", scroll to bottom from very top again, click on submodule, repeat as needed.
• Either eliminate the API reference section or move almost all of our docs there. Right now:
  1. Some APIs are easy to find on the left, but some require digging through several levels of API reference, and
  2. the API reference and our other docs are often redundant.
     • Since AFAIK most public APIs are addressable as composer.one_level_deep.ThingToUse, I propose eliminating the hierarchical API reference and just having a page for every one_level_deep module, which would include both tutorial content as needed and the full API for that module (including child modules) at the bottom. Mirrors what HF transformers docs do, and combined tutorial + full docs in each module docstring mirrors what torch does.

[mvpatel2000]

This is done!