Skip to content

Commit 6c68242

Browse files
committed
Improve contributing docs
1 parent 808ba74 commit 6c68242

1 file changed

Lines changed: 24 additions & 8 deletions

File tree

docs/development/contribute_docs.md

Lines changed: 24 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -16,36 +16,52 @@
1616

1717
# Contribute to documentation
1818

19-
The MaxText documentation website is built using [Sphinx](https://www.sphinx-doc.org) and [MyST](https://myst-parser.readthedocs.io/en/latest/). Documents are written in [MyST Markdown syntax](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html#syntax-core).
19+
The MaxText documentation website is built using [Sphinx](https://www.sphinx-doc.org)
20+
and [MyST](https://myst-parser.readthedocs.io/en/latest/). Documents are written
21+
in [MyST Markdown syntax](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html#syntax-core).
2022

2123
## Building the documentation locally (optional)
2224

23-
If you are writing documentation for MaxText, you may want to preview the documentation site locally to ensure things work as expected before a deployment to Read The Docs.
25+
If you are writing documentation for MaxText, you may want to preview the
26+
documentation site locally to ensure things work as expected before a deployment
27+
to [Read The Docs](https://readthedocs.org/).
2428

25-
First, make sure you [install MaxText from source](install-from-source) and install the necessary dependencies. You can do this by navigating to your local clone of the MaxText repo and running:
29+
First, make sure you [install MaxText from source](install-from-source) and
30+
install the necessary dependencies. You can do this by navigating to your local
31+
clone of the MaxText repo and running:
2632

2733
```bash
2834
pip install -r src/dependencies/requirements/requirements_docs.txt
2935
```
3036

31-
Once the dependencies are installed, you can navigate to the `docs/` folder and run:
37+
Once the dependencies are installed, you can navigate to the `docs/` folder and
38+
run:
3239

3340
```bash
3441
sphinx-build -b html . _build/html
3542
```
3643

37-
This will generate the documentation in the `docs/_build/html` directory. These files can be opened in a web browser directly, or you can use a simple HTTP server to serve the files. For example, you can run:
44+
This will generate the documentation in the `docs/_build/html` directory. These
45+
files can be opened in a web browser directly, or you can use a simple HTTP
46+
server to serve the files. For example, you can run:
3847

3948
```bash
4049
python -m http.server -d _build/html
4150
```
4251

43-
Then, open your web browser and navigate to `http://localhost:8000` to view the documentation.
52+
Then, open your web browser and navigate to `http://localhost:8000` to view the
53+
documentation.
4454

4555
## Adding new documentation files
4656

47-
If you are adding a new document, make sure it is included in the `toctree` directive corresponding to the section where the new document should live. For example, if adding a new tutorial, make sure it is listed in [the `docs/tutorials.md`](https://github.com/AI-Hypercomputer/maxtext/blob/7070e8eecbea8951c8e5281219ce797c8df1441f/docs/tutorials.md?plain=1#L38) toctree.
57+
If you are adding a new document, make sure it is included in the `toctree`
58+
directive corresponding to the section where the new document should live. For
59+
example, if adding a new tutorial, make sure it is listed in
60+
[the `docs/tutorials.md`](https://github.com/AI-Hypercomputer/maxtext/blob/7070e8eecbea8951c8e5281219ce797c8df1441f/docs/tutorials.md?plain=1#L38)
61+
toctree.
4862

4963
## Documentation deployment
5064

51-
The MaxText documentation is deployed to [https://maxtext.readthedocs.io](https://maxtext.readthedocs.io) on any successful merge to the main branch.
65+
The MaxText documentation is deployed to
66+
[https://maxtext.readthedocs.io](https://maxtext.readthedocs.io) on any
67+
successful merge to the main branch.

0 commit comments

Comments
 (0)