misc: Add sphinx stdlib documentation (#335)
This PR adds documentation to the standard library using Sphinx. For details on how the documentation was generated, refer to https://gem5.atlassian.net/browse/GEM5-1314. Currently, some modules like `dramsys` and `mesi_three_level` appear as blank pages. To view the current state of the documentation locally, run: `cd docs/_build/html; python3 -m http.server 8000` --------- Co-authored-by: ivanaamit <ivanamit91@gmail.com>
This commit is contained in:
committed by
Bobby R. Bruce
parent
b6c941c9ca
commit
e146f1b2bc
37
docs/README
Normal file
37
docs/README
Normal file
@@ -0,0 +1,37 @@
|
||||
# How to build Sphinx documentation
|
||||
|
||||
In order to build documentation for the standard library, first install sphinx. Run these commands in the `gem5` directory.
|
||||
|
||||
```bash
|
||||
python3 -m venv build/
|
||||
source build/bin/activate
|
||||
pip install sphinx
|
||||
|
||||
```
|
||||
|
||||
Next, build gem5, then cd to the `docs` directory.
|
||||
|
||||
```bash
|
||||
scons build/ALL/gem5.opt
|
||||
cd docs
|
||||
```
|
||||
|
||||
In the `docs` directory, run `../build/ALL/gem5.opt gem5-sphinx-apidoc -o . ../src/python/gem5 -F -e` in order to generate the RST files.
|
||||
|
||||
To generate the documentation, run `SPHINXBUILD="../build/ALL/gem5.opt gem5-sphinx" make html`
|
||||
|
||||
In order to view this documentation as a website, run the following commands while still in the `docs` directory:
|
||||
|
||||
```bash
|
||||
cd _build/html
|
||||
python3 -m http.server 8000
|
||||
```
|
||||
|
||||
If you want to use a different Sphinx theme, follow these steps:
|
||||
|
||||
- Install the desired theme, e.g., `pip install sphinx-rtd-theme`
|
||||
- Update the `html_theme` in `docs/conf.py` by setting `html_theme = "sphinx_rtd_theme"`
|
||||
- Run `SPHINXBUILD="../build/ALL/gem5.opt gem5-sphinx" make html` in the `docs` directory to apply the changes.
|
||||
|
||||
Note: We are aware that some modules currently display a blank page in the documentation.
|
||||
This will be addressed in the future.
|
||||
Reference in New Issue
Block a user