Reorganize Documentation structure

[billbrod]

In addition to docstrings, examples, and tutorials that we need, we need some good basic documentation that explains the idea behind this package, points to the associated papers, and lays out the basic ideas. Also should include stuff about basic API, how to use the various abstractions / more general functionality (coarse-to-fine optimization, plotting, etc). Those might not be necessary for final users, but are necessary for us while we work on the core.

Some potentially helpful info: open source guides from Github, Mozilla Science Working Open Workshop.

[billbrod]

Specific things we need:

• tips for how to speed up models (e.g., avoid torch.stack)
• how to work with plot_representation_error

[billbrod]

See diataxis for a framework on technical documentation that looks helpful.

[NickleDave]

Here's one potential schema you could use. It borrows fro the diataxis framework but also the structure of core packages like numpy, scipy, etc

• getting started
  • installation
  • quickstart
• reference
  • model requirements
  • citation
  • reproducibility
• API
• user guide
• basically, everything else: tutorials, how-tos

[billbrod]

Copying Daniela's relevant comments about schema (from pyOpenSci review) in here as well:

The documentation webpage is confusing and not well organized, but it can be easily improved. A possible organization would be:

->Presentation
-> Introduction
-> Installation
-> Quick start
-> Citation Guide

->Modules
-> Metric
-> Simulate
-> Synthesize
-> tools
-> Display and animate functions

->Tutorials and examples
-> Eigendistortions
...
-> Reproducing Wand and Simoncelli
-> Extending existing synthesis objects

->Advanced Usage
-> Model requirements
-> Synthesis object design
-> Extending...
-> API
-> Tips and tricks
-> Reproducibility

In the section "Modules" it would be presented the general goal and content of the module and, eventually, some code snap-shots. Not all the modules need to be present, only the most relevant and/or difficult to use. The code snap-shots can be from the tutorials and examples already existing, In addition, there can be links between the modules and tutorial sections

In the section "Tutorials and examples" would be all the tutorials already on the website.