|
16 | 16 |
|
17 | 17 | # Contribute to documentation |
18 | 18 |
|
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). |
20 | 22 |
|
21 | 23 | ## Building the documentation locally (optional) |
22 | 24 |
|
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/). |
24 | 28 |
|
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: |
26 | 32 |
|
27 | 33 | ```bash |
28 | 34 | pip install -r src/dependencies/requirements/requirements_docs.txt |
29 | 35 | ``` |
30 | 36 |
|
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: |
32 | 39 |
|
33 | 40 | ```bash |
34 | 41 | sphinx-build -b html . _build/html |
35 | 42 | ``` |
36 | 43 |
|
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: |
38 | 47 |
|
39 | 48 | ```bash |
40 | 49 | python -m http.server -d _build/html |
41 | 50 | ``` |
42 | 51 |
|
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. |
44 | 54 |
|
45 | 55 | ## Adding new documentation files |
46 | 56 |
|
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. |
48 | 62 |
|
49 | 63 | ## Documentation deployment |
50 | 64 |
|
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