Setup sphinx for documentation

[fyliu]

Overview

As PeopleDepot and python developers, it helps to have well-organized documentation. We should set up sphinx for this purpose.

Sphinx is the standard documentation tool for python projects that supports many useful formatting elements. Furo is a clean theme with good layout, legible night mode. In the spirit of ease of use for the API developers, we should set up MyST parser for sphinx to support CommonMark markdown documentation rather than the default restructured-text. Devs can still use rST according to preference.

Action Items

• setup sphinx doc tool
  • make note of any problems, and how to run it for development
• setup MyST parser
  • make note of files changed to switch over to markdown
• setup furo theme
• setup automation to generate docs
  • document the action if it's custom
• document how things work

Resources/Instructions

Sphinx
MyST parser
furo

potentially useful

sphinx tutorial

Discussion

There are several related suggestions here:

• sphinx addresses the desire to use the documentation system of choice for python projects
  • it's useful to be familiar with it if contributors want to go on to a career working with python
  • it supports many useful formatting elements such as tabbed content
  • has many useful extensions
• MyST parser addresses the concern that many current devs are more familiar with markdown than with restructured text
• furo theme addresses more personal concerns
  • 3 column interface with page contents
  • clean and minimal, but not too spacious like material design
  • partly inspired by sphinx-book-theme, which is also very nice
  • uses sphinx-design, which provides ui elements like synchronized tabs and dropdowns

[fyliu]

Status Update

1. Progress - I setup an example at peopledepot.readthedocs.io. It has a few modifications as examples of the kind of things we can do with documentation to make it more clear and useful.
2. Blockers - none
3. Availability - at least 8 hours in the next 7 days
4. ETA - It should take 4-5 hours

I was working on this before my ssd died a few weeks ago. Now I can continue.

These are the remaining things to do:

1. Clean up the commits
2. Add documentation

[fyliu]

I'm still working on the documentation. It should be complete by next meeting.

[fyliu]

This is not relevant anymore since we've decided to use mkdocs instead. Closing this issue

• See Set up mkdocs site in PD #166