Repository for Trio documentation (under development)

• Clone this project
• Install Python 3 For help getting Python installed, see "Properly Installing Python".
• Install a Python Virtual Environment.
  In this example, I use venv, but use whichever you prefer.

  cd trio-docs # where you cloned the trio-docs repository
  
  # Creates a virtual environment using Python 3 in the venv folder
  python3 -m venv venv 
  
  # Activate the virtual environment
  # IMPORTANT: Run the next line **each time** you start a new shell window/tab
  source venv/bin/activate

• Install the dependencies (that is the project's required Python packages)

  cd trio-docs # where you cloned the trio-docs repository
  
  python -m pip install -r dev-requirements.txt
  python -m pip install -r requirements.txt

Once installed, you can preview the doc locally as you make changes:

• Run the mkdocs serve command locally in a separate terminal window and keep it running:

  cd trio-docs # where you cloned the trio-docs repository
  source bin/venv/activate # Do this once when opening a shell or if the shell prompt no longer displays `(venv)`
  
  mkdocs serve

  By default, this runs a local web server that hosts the documentation at http://127.0.0.1:8000/ .

• Preview the site in your Web browser.
  Most changes will update automatically as you edit.
  Configuration and navigation changes will require restarting mkdocs serve.

cd trio-docs # where you cloned the trio-docs repository
source venv/bin/activate # Do this once when opening a shell or if the shell prompt no longer displays `(venv)`

mkdocs build

This does not generate the website's PDF version.

To export the website as a PDF:

cd trio-docs # where you cloned the trio-docs repository
source venv/bin/activate # Do this once when opening a shell or if the shell prompt no longer displays `(venv)`

MKDOCS_EXPORTER_PDF=true  mkdocs build

The PDF file is generated insite/trio-docs.pdf.

To find unused (orphaned) files in the project:

CHECK_UNUSED_FILES=true mkdocs build -s

To list broken links, we use mkdocs-htmlproofer-plugin:

CHECK_BROKEN_LINKS=true mkdocs build --quiet

You can contribute to the Trio documentation by correcting typos or suggesting new content.

cd trio-docs # where you cloned the trio-docs repository

# Activate the Python virtual environment 
#  (if the shell prompt does not display `(venv)`)
source venv/bin/activate

# Declare the official remote trio-docs GitHub repository 
# The remote repository name convention is:
# - origin denotes your copy of the `trio-docs` repository on GitHub
# - upstream denotes the official `trio-docs` repository on GitHub
# You already created `origin` before.
# `upstream` does not exist yet, we now need to create it.
#
# These are shortcuts for the remote repositories 
#   short name => long name (URL)
# We use the short name not to memorize and type the long name (see line below) each time we need to interact with it.
#
git remote add upstream https://github.com/nightscout/trio-docs.git

# Fetch the changes from the remote repositories
git fetch origin
git fetch upstream

# Jump on the `dev` branch
# `dev` contains the source code for the site ready to be deployed)
git switch dev

# Bring recent changes for the `dev` branch back from the official trio-docs repository (`upstream`)
git merge upstream/dev

# Example: We want to add a FAQ page in the `docs/resources/` folder

# Create (`-c`) and jump on a new feature branch where to add the FAQ page
#
git switch -c add_FAQ_page

# Create then edit the new FAQ file (`faq.md`)
MY_FAVORITE_EDITOR_HERE docs/resources/faq.md

# Edit, preview, repeat...
# until you are satisfied with the changes.

# ➡️ 🏬: Add the FAQ page to the warehouse
git add docs/resources/faq.md

# 🏬 ➡️ 🚚: Move all the changes from the warehouse into your **local** repository 
git commit -am "Add FAQ page"

# 🚚 ➡️ ⛅️: Push your feature branch `doc/add_FAQ_page` to your remote repository
git push -u origin add_FAQ_page

• Now open the official trio-docs repository in your Web browser https://github.com/nightscout/trio-docs/pulls
• Click the pull-requests tab
  This page displays a box saying you can create a Pull-Request for your branch.
• Click the button to do so, then follow the instructions.

• Create a feature branch (aka. topic branch)

  git switch dev
  git switch -c feature/add_dependency_XXX

• Add the pinned version of the new package to the requirements.in file

    MY_FAVORITE_EDITOR_HERE requirements.in
    
    # Add the pinned version of the package to `requirements.in
    XXX_PACKAGE_NAME_HERE==XXX_PACKAGE_VERSION_HERE

  For example, to add the mkdocs-exporter package version 6.1.1, I added the following line to the requirements.in file:

  mkdocs-exporter==6.1.1
  

• Generate requirements.txt

    cd trio-docs
    
    # IMPORTANT: The project's virtual environment MUST be activated first
    source venv/bin/activate
    
    # Remove the already installed packages in case you need to start from a blank slate
    # python -m pip freeze --exclude-editable | xargs python -m pip uninstall -y
    
    # Install the development packages
    # (among which `pip-tools` that contains `pip-compile`)
    pip install -r dev-requirements.txt
    
    # Install the direct dependencies (listed in `requirements.in`
    # This also installs the indirect dependencies these packages depend upon.
    pip install -r requirements.in
    
    # Add code/doc using this package and test until it is ready.
    
    # Generate the `requirements.txt` file from `requirements.in`
    pip-compile
    
    # Commit the changes (where XXX denotes the package name)
    git add requirements.in requirements.txt
    git commit -m "➕ Add dependency: XXX"
    
    # Push your feature branch to your `origin` repository
    git push -u origin feature/add_dependency_XXX

• Create a Pull Request with your changes:
  • Open your clone repository of trio-docs on GitHub (https://github.com/YOUR_USERNAME/trio-docs)
    • Click the Pull Requests tab
    • Click "Compare & pull request" in the yellow banner next to your branch name

Using the # sign shows a chapter on the menu/index. The number of #'s determines the level.

Example:

# README

## Tips & Tricks

### Add a Chapter

### Link to Another File

When linking to another Markdown file (ending with .md) in another directory, the link must start with ../.

In the below example, assuming you are editing docs/install/index.md, to add a link pointing to docs/configuration/new-user-setup.md with the text new user setup:

Now on to the [new user setup](../configuration/new-user-setup.md)

Do not forget the .md suffix.

docs                    <== ../ 
├── install             <== ./ denotes the current folder (docs/install/)
│ └── index.md          <== You are here (the current file)
│   
├── configuration       <== ../configuration
│ └── new-user-setup.md <== ../configuration/new-user-setup.md

Trio's glossary is a dictionary for the acronyms and technical terms used in the documentation. It explains them in simple terms. It is kind of a personal translator for all the diabetes jargon you will find there.

The glossary is composed of a source file and a generated Markdown page.
The website uses the Markdown page of the glossary.

Updating the glossary is a 3-step manual process:

1. Modify the glossary source file (includes/glossary.txt ) to add/update/remove entries.
2. Generate the glossary Markdown page (docs/faqs/glossary.md) using this handy shell script:

   ./make-glossary.sh

   ---
   title: Generate the Glossary Page
   ---
   flowchart LR
     subgraph Glossary Source
       text_glossary[/ includes/glossary.txt /]
     end
     subgraph Run Shell Script
       generator{ ./make-glossary.sh }
     end
     subgraph Glossary Page
       markdown_glossary[/ docs/faqs/glossary.md /]
     end
   
     text_glossary --> generator --> markdown_glossary
   

   Loading
3. Commit the changed files (glossary source file and generated page):

   git add includes/glossary.txt docs/faqs/glossary.md
   git commit -m "Update Glossary: ..."

When the same section of text is repeated in several files, it is time to consolidate all these occurrences into a single file and include it in all relevant files, that means:

• Move the existing redundant section of text to a new dedicated file.
• Replace all redundant occurrences of that section with an include directive in all the files that previously defined it.

Let's break down these steps:

1. Create a new file
   Create a Markdown file in the docs/includes/ folder, for example:
   docs/includes/version-compatibility-matrix.md.
2. Move the duplicated content
   Move the duplicated section into this new file.
3. Mark it as includable
   Wrap the content within <!--include-markdown-start--> and <!--include-markdown-end--> comments to define what will be included.

     Content before the start comment will not be included.
     
    <!--include-markdown-start-->
    …your reusable content (duplicated text section)…
    <!--include-markdown-end-->
   
     Content after the end comment will not be included.

4. Replace each original redundant section with an include directive
   In each file that originally contained the duplicated text, replace it with the following include directive:

   {%
     include-markdown "includes/version-compatibility-matrix.md"
   %}

   Make sure the path is relative to the docs/ folder.
5. Update mkdocs.yml
   To prevent the included file from appearing in the navigation or triggering a warning, add it to the not_in_nav section:

   not_in_nav: |
     includes/version-compatibility-matrix.md

This is what an admonition looks like in Sphinx:

:::{warning}
This is not medical advice.  
Understanding the changes you are making is important, and always be sure to exercise caution.  
When in doubt, consult your diabetes care team for settings guidance.
:::

Here is what the same admonition looks like in "Mkdocs-material":

!!! warning
    
    This is not medical advice.
    Understanding the changes you are making is important, and always be sure to exercise caution.
    When in doubt, consult your diabetes care team for settings guidance.

where:

• The title line contains (in this order):
  • 3 exclamation characters !!!
  • a space
  • the admonition type, (warning in the above example)
  • a space
  • an optional title (none in this example) surrounded by double quotes. We could have used "Not a Medical Advice" to set a title.
• Each line of the body text (lines below the title)
  must be indented 4-spaces. I use the ␠ character to denote a space ( ) in the example below. to make it stand out. Do not copy and paste this, it is only for visual purposes.

    !!! warning "Not medical advice"
    ␠␠␠␠
    ␠␠␠␠ Understanding the changes you are making is important [...]