Add Docs

[fubuloubu]

Options:

• https://www.mkdocs.org/
• https://pdoc3.github.io/pdoc/
• https://www.sphinx-doc.org/en/master/index.html

Tools:

• https://docs.python.org/3/library/doctest.html
• https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html
• https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
• https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html
• https://github.com/PyCQA/pydocstyle
• https://github.com/astropy/pytest-doctestplus

[fubuloubu]

• https://github.com/squidfunk/mkdocs-material
• https://myst-parser.readthedocs.io/en/latest/using/intro.html
• https://github.com/mkdocstrings/mkdocstrings/
• https://www.it3.be/2020/08/14/using-mkdocs-with-gh-pages/

[fubuloubu]

https://github.com/click-contrib/sphinx-click

[lost-theory]

@sabotagebeats and I talked about splitting up the docs work on Monday. Here are some next steps:

• eip712 feature/sphinx-docs branch:
  • add the autosummary extension
  • add the doctest extension
  • figure out how to build and host the docs on Github Pages
  • add logic for latest vs stable vs. tagged release directories (can do this in the publish job, use GITHUB_REF)
  • add version picker widget
  • merge the branch to main
  • port the changes over to project-template
• copy the project-template Sphinx configs to each repo (just ape for now)
• increase documentation coverage everywhere Sphinx is set up (documenting each module, class, and function)
• add sphinx-github-changelog

[fubuloubu]

Docs Outline

End User Docs

• "ape as an application" usage guide
  • Project layout
  • Configuration file
  • "core plugin CLI" endpoint usage guide (Click generated docs?)
    • ape accounts
    • ape compile
    • ape test
    • ape console
  • Plugin installation guide
    • ape plugins
• "ape as a package" usage guide
  • project object (and Project class)
  • accounts object
  • networks object
  • other objects... (compilers, etc.)
• Using the Console
  • Inspecting and Debugging Transactions
• Writing and Using Scripts
• Writing and Running Tests
  • Debugging Tests
  • "Fork Mode" testing
  • Measuring and Viewing Coverage
  • Property Tests
  • Stateful Testing
• Deploying Packages

Plugin Writer Docs

• Overall architecture flow
  • Plugin Registration process flow
    • API Object registration
    • CLI registration
  • Compilation process flow
    • contracts/ folder
    • Source type
    • Compiler manager
    • CompilerAPI plugins
    • ContractType type
    • Project manager
  • Account registration process flow
    • accounts manager
    • AccountAPI/AccountContainerAPI plugins
    • Signing messages and transactions via AccountAPI
  • Transactional process flow
    • networks manager
    • EcosystemAPI plugins
    • NetworkAPI plugins
    • ProviderAPI plugins
    • ExplorerAPI plugins
    • ContractInstance type and encoding via EcosystemAPI
  • Test process flow
    • Writing fixtures
    • TBD...
  • Argument conversion process flow
    • TBD...
• Writing CLI plugins

Internal Reference

• docstrings, etc.

[antazoey]

Will create separate tickets for the last 3 bullets