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>

.gitignore

@@ -10,6 +10,7 @@ cscope.out
 .*.swo
 m5out
 /src/doxygen/html
+/docs/_build
 /ext/dramsim2/DRAMSim2
 /ext/mcpat/regression/*/*.out
 /util/m5/*.o

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)

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.

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

docs/gem5-sphinx

@@ -0,0 +1 @@
+import sphinx.__main__

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())