From: Sean Cross <sean@xobs.io>
Date: Fri, 24 Jul 2020 07:47:59 +0000 (+0800)
Subject: doc: socdoc: document `sphinx_extensions` parameter
X-Git-Tag: 24jan2021_ls180~59^2
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=7fecfbf8e0636453d6f540084ad49ab78afe50c1;p=litex.git

doc: socdoc: document `sphinx_extensions` parameter

This adds documentation for `sphinx_extensions` which can be used to add
additional features to output.

Signed-off-by: Sean Cross <sean@xobs.io>
---

diff --git a/doc/socdoc.md b/doc/socdoc.md
index 33329207..c565c54b 100644
--- a/doc/socdoc.md
+++ b/doc/socdoc.md
@@ -26,7 +26,9 @@ from litex.soc.doc import generate_docs, generate_svd
     builder = Builder(soc)
     vns = builder.build()
     soc.do_exit(vns)
-    generate_docs(soc, "build/documentation")
+    generate_docs(soc, "build/documentation",
+                        project_name="My SoC",
+                        author="LiteX User")
     generate_svd(soc, "build/software")
 ```
 
@@ -112,6 +114,27 @@ You may pass a single string to the constructor, in which case the first line be
 
 Note that the default documentation format is `rst`. You can switch to markdown by passing `format="markdown"` to the constructor, however support is not very good.
 
+### Additional Sphinx Extensions
+
+The `generate_docs()` call produces Sphinx output. By default it only includes
+additional extensions for `sphinxcontrib.wavedrom`, which is required to display
+register listings. You can add additional modules by passing an array to
+`generate_docs()`. For example, to add `mathjax` support:
+
+```python
+    generate_docs("build/documentation", sphinx_extensions=['sphinx.ext.mathjax'])
+```
+
+By default, `socdoc` unconditionally overwrites all files in the output
+directory, including the sphinx `conf.py` file. To disable this feature
+so you can customize your own `conf.py` file, pass `from_scratch=False`:
+
+```python
+    generate_docs("build/documentation", from_scratch=False)
+```
+
+In this case, `conf.py` will only be created if it does not already exist.
+
 ### External Documentation
 
 You can have external documentation by passing `file` to the constructor.