Rewrite the docs

[Archmonger]

Beta Docs: https://github.com/reactive-python/reactpy/tree/new-docs

Current Situation

It is difficult for new contributors to modify the docs, due to the current usage of reStructuredText (RST). Also the current verbiage is somewhat hard to understand for beginners.

Proposed Actions

Convert the current docs from reStructuredText (sphinx) to Markdown (mkdocs).

These new docs should be a 1:1 rewrite of ReactJS's documentation.

Also consider using these plugins

• https://github.com/jimporter/mike for docs versioning
• https://github.com/fralau/mkdocs_macros_plugin for code actions
• https://github.com/greenape/mknotebooks or https://github.com/danielfrg/mkdocs-jupyter for embedding jupyter into the page

---

Related issues

• 845

• 779

• 653

• 647

• 349

• 568

• 780

[rmorshea]

Useful conversation to inform our decision to use mkdocs: https://github.com/encode/httpx/discussions/1220

It looks like they stuck with mkdocs in the end.

[Archmonger]

I created a draft of the new docs structure using mkdocs. Used django-idom docs as the initial template.

https://github.com/Archmonger/idom-docs

Currently, the only thing that has been developed is the navigation names, and website theme.

---

Can be previewed by typing the following:

pip install -r build-docs.txt
mkdocs serve

[rmorshea]

Looking at the docs for Textual (a popular terminal UI framework) I found a list of mkdocs plugins and extensions we might want to consider using.

[rmorshea]

mktestdocs also looks interesting.