diff --git a/.gitignore b/.gitignore index 36ba603fb6..dcc09fc1c6 100644 --- a/.gitignore +++ b/.gitignore @@ -10,6 +10,7 @@ cscope.out .*.swo m5out /src/doxygen/html +/docs/_build /ext/dramsim2/DRAMSim2 /ext/mcpat/regression/*/*.out /util/m5/*.o diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000..d4bb2cbb9e --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/README b/docs/README new file mode 100644 index 0000000000..540829a614 --- /dev/null +++ b/docs/README @@ -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. diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000000..8bacc4dd85 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,42 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "gem5" +copyright = "" +author = "" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.viewcode", + "sphinx.ext.todo", +] + +templates_path = ["_templates"] +exclude_patterns = [ + "_build", + "Thumbs.db", + ".DS_Store", + "build/lib64/python3.8/site-packages", + "build/lib/python3.8/site-packages", +] + +language = "en" + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "alabaster" +html_static_path = ["_static"] + +# -- Options for todo extension ---------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration + +todo_include_todos = True diff --git a/docs/gem5-sphinx b/docs/gem5-sphinx new file mode 100644 index 0000000000..5b4550e10d --- /dev/null +++ b/docs/gem5-sphinx @@ -0,0 +1 @@ +import sphinx.__main__ diff --git a/docs/gem5-sphinx-apidoc b/docs/gem5-sphinx-apidoc new file mode 100644 index 0000000000..6c2ac21f0d --- /dev/null +++ b/docs/gem5-sphinx-apidoc @@ -0,0 +1,14 @@ +import re +import sys + +extensions = ['myst_parser'] + +source_suffix = { + '.md': 'markdown', + '.py': 'markdown' +} + +from sphinx.ext.apidoc import main +if __name__ == '__m5_main__': + sys.argv[0] = re.sub(r'(-script\.pyw|\.exe)?$', '', sys.argv[0]) + sys.exit(main())