Sphinx documentationΒΆ
Our documentation website is generated with the Sphinx framework and implements the Furo theme.
Here, you will find some documentation to get you started when contributing to this website. For further information, please refer to Sphinx and Furo documentation.
Local buildΒΆ
- Prerequisites
Python 3.9+
- Clone the repository
Begin by cloning the ZAS/EAK CopilotGPT repository to your local machine to get the necessary project files.
git clone https://github.com/CdC-SI/eak-copilot.git cd eak-copilot
- Install dependencies
doc/requirement.txt
contains Sphinx and several Sphinx extension packages that we use within the project. The other files contain packages required for building the CopilotGPT project, and thus for building the Sphinx documentation.pip install -r doc/requirements.txt pip install -r src/copilot/requirements.txt
- Run the build
sphinx-build -M html doc _build
An index.html
document can now be found in the _build/html/
directory. You can open it with your favorite browser and start exploring!
StructureΒΆ
Files related to the documentation can be found inside the doc/
directory.
Currently, our /doc folder is structured as follows.
doc
βββ _static
β β css
β β img
βββ guidelines
β β sphinx.rst <--- you are here
β β ...
βββ introduction
β β ...
βββ documentation
β β ...
βββ conf.py
βββ index.rst
βββ ...
All the remaining folders contains .rst
or .md
files only, each file represents a webpage.
Especially, index.rst contains several βToc treesβ which define the architecture of the website and build the sidebar on the left.
Each toctree
defines a theme. Currently, the website is split into 3 of theme: Introduction, Guidelines, and Documentation.
Thus, there are 3 toctree
defined in doc/index.rst, one for each theme, whose each structure can be visualized as below.
Introduction
βββ introduction/intro (EAK-Copilot)
βββ introduction/start (Getting Started)
βββ introduction/udpate (Updates)
Introduction
βββ guidelines/opensource (Open-Source collaboration)
βββ guidelines/documentation (Documentation standards)
βββ guidelines/sphinx (Sphinx documentation) <--- you are here
Documentation
βββ documentation/api (API)
βββ documentation/indexing/index (IndexingPipeline)
β β crawler
β β scraper
β β parser
β β chunker
βββ documentation/survey/index (SurveyPipeline)
β β api (Survey pipeline API)
βββ documentation/rag/index (RAG)
β β retrieval (RetrievalPipeline)
βββ documentation/chatbot/index (Chatbot)
β β generation (GenerationPipeline)
βββ documentation/autocomplete/index (Autocomplete)
β β exactmatch
β β fuzzyserach
β β similaritysearch
βββ documentation/gui/index (GUI)
β gui
In particular, we can observe the Documentation toctree
pointing at several index.rst files, each containing its own toctree
pointing at subsections.
We can also observe that toctree
has its corresponding directory, inside which we can find its .rst files.
reStructuredText (reST)ΒΆ
Sphinx uses by default the reStructuredText (reST) markup language, which filename extension is .rst
.
You can find the full documentation here, we provide below a short introduction to this language.
We also recommend having a look at the Furoβs version of the markup documentation, which is the Sphinx theme we are using. Especially, the admonitions can be useful and enhance your code descriptions.
Headers conventionΒΆ
The underline and optional overline with a punctuation character needs to be at least as long as the text. Normally, there are no heading levels assigned to specific character, but the recommended way is as follow.
####################################
Part -- Number Signs above and below
####################################
************************************
Chapter -- Asterisks above and below
************************************
Title -- Number Signs
#####################
Suptitle -- Asterisks
*********************
Section -- Equal Signs
======================
Subsection -- Hyphens
---------------------
Subsubsection -- Circumflex
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Paragraph -- Double Quotes
""""""""""""""""""""""""""
Inline markupΒΆ
*italic text*
**bold text**
``code samples``
ListsΒΆ
* This is a bulleted list.
* It has two items, the second
item uses two lines,
* and a nested list
* and some subitems
* the parent list continues
1. This is a numbered list.
2. It has two items too.
#. This is a numbered list.
#. It has two items too.
Note that both *
and -
signs work for a bulleted list.
HyperlinksΒΆ
Hyperlinks can take various forms, so here's a list of them:
- standalone hyperlink: https://python.org/
- hyperlink using references: `link <link>`__
- hyperlink with inline URL: `link <https://python.org/>`_
- hyperlink to a different page: :doc:`link <../quickstart>`
- hyperlink to a specific API element: :class:`pathlib.Path`
.. _link: https://python.org/
ImageΒΆ
.. image:: https://source.unsplash.com/200x200/daily?cute+animals
Code BlocksΒΆ
Below is a code blocks::
Indenting content by 4 spaces, after a line ends with "::".
This will have default syntax highlighting (highlighting a few words and "strings").
.. code::
You can also use the code directive, or an alias: code-block, sourcecode.
This will have default syntax highlighting (highlighting a few words and "strings").
.. code:: python
print("And with the directive syntax, you can have syntax highlighting.")
.. code:: none
print("Or disable all syntax highlighting.")
API documentationΒΆ
.. automodule:: indexing_api
:members:
.. autoclass:: indexing.scraper.Scraper
:members:
Markdown (MyST)ΒΆ
Although reStructuredText is the base language for Sphinx, through the MyST extension, it also supports .md
files.
You can use .md
if you feel more comfortable with it.
Read their documentation for Sphinx related functionalities, and also Furoβs documentation which specifies MyST usages in the second tab of their code blocks.