General-purpose documentation (Swagger / Sphinx / Readthedocs, etc)

[joeflack4]

Individual Steps

1. Decide on implementation

Options

• Readthedocs
• Something home-grown

2. Create docs

2.1 Migrate existing documentation from GitHub readme

2.2 Add new documentation

• 2.2.1 Add new docs to new implementation
• 2.2.1 Add new docs to new GitHub readme

2.5 Optional: Add Open API / Swagger docs

2.5.1 Add Swagger docs

2.5.2 Add a page that links to Swagger docs from main docs

3. Host docs

3.1 Host locally (vs separate deployment

3.2 Set endpoint (/docs, /v1/docs, docs/v1 /)

3.3 Disambiguate from RESTful web service (/rest, /v1/rest, rest/v1)

4. Set up process to update docs as new releases are made

4.1 Automatic swagger updates

4.2 Sync updates between general implementation and readme

5. Optional Bonus steps

5.1 Searchability

If you want full support for searching inside your Read the Docs site you will need to install Elasticsearch.

5.2 Mimetype routing

Route the request to /docs or /rest depending on mimetype.

Task List

• [x] 1. Decide on implementation (e.g. Open API / Swagger spec)
• [x] 2. Create docs
• [x] 2.5 Optional: Add Open API / Swagger docs
• [x] 3. Host docs (local vs otherwise)
• [x] 4. Set up process to update docs as new releases are made
• [x] 5. Optional: Bonus steps

[joeflack4]

Finished.