Repository navigation
Rewrite the docs #863
Description
Beta Docs Live Preview: https://reactive-python.github.io/reactpy/
Beta Docs Source Code: 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
- Improve
use_contextdocs #845 - Use snake_case for components #779
- Embedding ReactPy via Template Tags #653
- Improve JavaScript components docs #647
- Add docs section for Common utils (e.g. the stuff in reactpy.widgets) #349
- Add Example of Bug Due to Mutation in "Dangers of Mutability" #568
- Explore JupyterLite-Sphinx for interactive examples in docs #780
Activity
rmorshea commentedon Dec 30, 2022
Useful conversation to inform our decision to use mkdocs: encode/httpx#1220
It looks like they stuck with mkdocs in the end.
Archmonger commentedon Dec 31, 2022
I created a draft of the new docs structure using
mkdocs. Useddjango-idomdocs 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:
rmorshea commentedon Jan 26, 2023
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 commentedon Jan 26, 2023
mktestdocs also looks interesting.
[-]Switch docs to mkdocs[/-][+]Rewrite the docs with mkdocs[/+][-]Rewrite the docs with mkdocs[/-][+]Rewrite the docs[/+]