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+

  1. Clone the repository

    Begin by cloning the EAK-Copilot repository to your local machine to get the necessary project files.

    git clone https://github.com/CdC-SI/eak-copilot.git
cd eak-copilot
  2. 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 Copilot project, and thus for building the Sphinx documentation.

    pip install -r doc/requirements.txt
pip install -r autocomplete/requirements.txt
pip install -r indexing/requirements.txt
pip install -r rag/requirements.txt
  3. 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
└── ...
conf.py is the Sphinx configuration files.
_static/ contains custom static files, such as stylesheets or images.

All the remaining folders contains .rst or .md files only, each file represents a webpage.

index.rst is the website homepage.
intro/ contains pages that introduce the Copilot project.
guidelines/ contains tutorials and best practices guidelines.
topics/ contains Copilot open sourced code documentation.

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.

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.