diff --git a/README.md b/README.md index eede0ae2..547c57c5 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ The System Level Documentation is the top documentation for Hardware, Projects, and some Linux documentation; it also has the ability to aggregate every other documentation into a single monolithic output/website. -## Building the documentation +## Build the documentation Ensure pip is newer than version 23. ``` @@ -19,9 +19,9 @@ Build the documentation with Sphinx. ``` The generated documentation will be available at `docs/_build/html`. -## Building the all documentations +## Build all documentations -It's possible to build all ADI's documentation at once. +It's possible to build all ADI's documentation at once in parallel. To generate it, considering Doctools is installed, do: ``` adoc aggregate -d docs_output diff --git a/docs/conf.py b/docs/conf.py index bc32af0b..ae02fc01 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -25,7 +25,14 @@ # -- External docs configuration ---------------------------------------------- -interref_repos = ['doctools', 'hdl', 'pyadi-iio', 'scopy', 'no-OS'] +interref_repos = [ + 'doctools', + 'hdl', + 'pyadi-iio', + 'scopy', + 'no-OS', + 'precision-converters-firmware', +] # -- Options for HTML output -------------------------------------------------- diff --git a/docs/contributing/creating_new_pages.rst b/docs/contributing/creating_new_pages.rst index cb350d93..eaa656d5 100644 --- a/docs/contributing/creating_new_pages.rst +++ b/docs/contributing/creating_new_pages.rst @@ -7,6 +7,19 @@ The first step on adding new content is to understand the :ref:`creating-new-pages documentation-structure`. Then, proceed with :ref:`creating-new-pages adding-content`. +.. _creating-new-pages template: + +Content templates and guidelines +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Templates and guidelines for specific types of content are available: + +.. toctree:: + :glob: + :titlesonly: + + template/* + .. _creating-new-pages documentation-structure: Documentation structure @@ -29,7 +42,7 @@ To create each "volume", two `toctrees `__ replicate the structure of the context top level. -For example, while in :git-documentation:`docs/index.rst#L19-L25` +For example, while in :git-documentation:`docs/index.rst#L24` we have: .. code:: rst @@ -38,21 +51,23 @@ we have: .. toctree:: :caption: Linux Kernel & Software :maxdepth: 2 + :glob: - linux/kuiper/index - linux/drivers/index - linux/kernel/index + linux/*/index -At the specific context toctree (:git-documentation:`docs/linux/index.rst#L6-L10`) +At the specific context toctree (:git-documentation:`docs/linux/index.rst#L9`) we have: .. code:: rst .. toctree:: + :glob: + + */index - kuiper/index - drivers/index - kernel/index +*Glob* is used to match any document that matches the pattern and avoids simple +but annoying merge conflicts of contributors adding pages to the same toctree +at the same time. Use case for the structure ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst deleted file mode 100644 index 6ba902be..00000000 --- a/docs/contributing/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -:orphan: - -Contributing and guidelines -=========================== - -.. toctree:: - - forking_publishing - creating_new_pages - docs_guidelines diff --git a/docs/contributing/template/eval.rst b/docs/contributing/template/eval.rst new file mode 100644 index 00000000..2081b1a8 --- /dev/null +++ b/docs/contributing/template/eval.rst @@ -0,0 +1,117 @@ +Evaluation Boards +================= + +Evaluation boards pages compile all content related to an evaluation board, +from the hardware overview, features, kit contents, hardware, user guides, +developer guides, and source code. + +A top-level template is available at +:git-documentation:`docs/contributing/template/example/eval.rst` +(:ref:`rendered