Repository for Loop Follow documentation (under development)

Install

• 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 loopfollowdocs # where you cloned the loopfollowdocs 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 loopfollowdocs # where you cloned the loopfollowdocs repository
  
  python -m pip install -r dev-requirements.txt
  python -m pip install -r requirements.txt

Run

Preview Changes

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 loopfollowdocs # where you cloned the loopfollowdocs 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.

Build the Website Locally

cd loopfollowdocs # where you cloned the loopfollowdocs 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.

Build the PDF

To export the website as a PDF:

cd loopfollowdocs # where you cloned the loopfollowdocs 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/loopfollowdocs.pdf.

Find Unused Files

To find unused (orphaned) files in the project:

CHECK_UNUSED_FILES=true mkdocs build -s

Note

We use the mkdocs-unused-files plugin.

Find Broken Links

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

CHECK_BROKEN_LINKS=true mkdocs build --quiet

Contribute

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

Using the Terminal

cd loopfollowdocs # where you cloned the loopfollowdocs repository

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

# Declare the official remote loopfollowdocs GitHub repository 
# The remote repository name convention is:
# - origin denotes your copy of the `loopfollowdocs` repository on GitHub
# - upstream denotes the official `loopfollowdocs` 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/loopandlearn/loopfollowdocs.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 loopfollowdocs 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 loopfollowdocs repository in your Web browser https://github.com/loopandlearn/loopfollowdocs/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.

Add a Package

Note

In this section, the terms Python package and dependency refer to the same thing.

• 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 loopfollowdocs
    
    # 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 loopfollowdocs on GitHub (https://github.com/YOUR_USERNAME/loopfollowdocs)
    • Click the Pull Requests tab
    • Click "Compare & pull request" in the yellow banner next to your branch name

FAQs

Note

Please add!

Add a Chapter

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

Tip

If you want to avoid a chapter ending up in the menu/index, use bold text by:

• either surrounding the text with 2-star signs **
• or adding <b> before the text and </b> after the text (without spaces).

Input	Result
**bold text**	bold text
<b>bold text</b>	bold text

Add a 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

Update the Glossary

LoopFollow'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: ..."

Note

Remember to commit these 2 files.

Tip

Separate the Title and Body with an Empty Line

• Adding a blank line (4 spaces indented) between the title and the body of the text makes a visual distinction for the reader. This is not required.
• When present in the body text, empty lines must also use a 4-space indentation.

Note

Mkdocs (the site generation engine) does not provide admonitions but mkdocs-material (the theme) does via the pymdownx Markdown extension.