From 7fecfbf8e0636453d6f540084ad49ab78afe50c1 Mon Sep 17 00:00:00 2001 From: Sean Cross Date: Fri, 24 Jul 2020 15:47:59 +0800 Subject: [PATCH] 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 --- doc/socdoc.md | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/doc/socdoc.md b/doc/socdoc.md index 33329207c..c565c54bb 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.