Proposal: Add a Writing Doc overview to the Contributing Guide #1886

Documentation request:

tl;dr add a Contributing Guide page / section containing the most common and/or arcade-specific sphinx concerns

This is a follow-up to a Discord conversation

What the overview should have

• What, where, when, and how to add things:

  • Purpose & location of each:
    • Programming guide
    • Examples
    • Tutorials
    • Docstrings

• Guidelines for instructions

  • Link an external source if other general doc exists
  • Put it on its own page otherwise

• Which build formats are priority support targets

  • Model off of NetBSD's tier system? (https://www.netbsd.org/ports/#tiers)
  • Arcade doc support tiers prioritize game prototyping and offline education
    1. Primary: HTML readthedocs
    2. Secondary: PDF, ePUB (?)
    3. When it doesn't interfere with the top 2 + time allows: Everything else

• The most common problems and how to deal with them

  • Sphinx header underlines must have correct length to avoid sphinx warnings which break build

  • tl;dr of how to link things

    • Agree on link name pattern / structure
    • Internal links: :ref:`internal_link_name`
    • Named external links need trailing underscore in the angle brackets:
      • Correct: `text <ref_name_>`_
      • Broken: `text <ref_name>`_
    • Intersphinx usage:
      • For Python doc: :py:class:`Sequence` should just work
      • pyglet should be the same way, but may require some prefixes
      • Unsure if should be included: :external: for link targets to headings

  • Toctrees

    • Item not in any toctree
    • @cspotcode's #include analogy
    • tl;dr of what a virtual hierarchy is
    • :hidden:, :includehidden: & furo

• Tips, such as HTML-only behavior

  • rawhtml isn't rendered in PDFs
    • Find out whether this applies to other build formats we might want (ePUB, other ebook formats)

• Links to more general sphinx doc

  • Practical smaller wikis (ie https://lpn-doc-sphinx-primer.readthedocs.io/en/stable/index.html#)
  • Google style guide, etc
  • Relevant parts of general sphinx doc

What the page should avoid

• Explanations of general Sphinx functionality when not directly relevant to arcade problems
• Detailed instructions