Edit this documentation

This page explains specifics about how this website is organized, and how to contribute to it. The following instruction assumes that you already have some base knowledge about git and markdown editing, and the instructions are based on the VS Code editor.

If you are not familiar with those tools, you can through the other tutorials that walks you through the process.

Preparing the environment

To edit this website, you need an environment with the necessary packages installed (mkdocs, themes and plugins). If you are editing with the GitHub Codespace, those should already be available to you.

Manual installation (if needed)

python -m venv ~/envs/mkdocs # create a virtural environment 
git clone git@github.com:Teoroo-CMC/TeChnicality-private.git technicality
cd technicality && pip install -e requirements.txt
mkdocs serve

The last command mkdocs serve starts a server that shows a live preview of the website. If you are using VS Code, you can also launch the server in your command palette (F1 then Run Task and find mkdocs serve), and see it in the "TERMINAL" tab in the bottoom panel.

Mkdocs basics

The website is built with mkdocs, a static site generator based on Markdown. This means you write the documentation as a set of Markdown files, and mkdocs compiles them into a website. With mkdocs, you write each page as one Markdown file, and define the (navigation) structure of the website in a config file.

This documentation has two versions. When you run mkdocs serve in this repo, you build the private version specified by mkdocs.yml; when the public site is built, mkdocs-public.yml will be used instead. You can see the difference in the nav section that controls the layout of the site:

mkdocs.yml

nav:
  - Home: index.md
  - Tutorial:
      - Overview: tutorial/overview.md
      - PE build: tutorial/PEbuild.md
      - Dielectric constant: tutorial/opticaldielectric.md
      - pKa calculation: tutorial/Alicia.md
      - Edit this site:
          - Overview: tutorial/this_site/overview.md
          - AIMD: tutorial/AIMD.md
          - H2WritePaper: tutorial/h2writepaper.md
          - VS Code: tutorial/this_site/vscode.md
          - Markdown: tutorial/this_site/markdown.md
          - Git & GitHub: tutorial/this_site/git.md
      - Integral capacitance: tutorial/Integral_capacitance.md
  - Simulate:
      - Overview: simulate/overview.md
      - AML Models: 
          - Open Dataset: simulate/aml/pinn_ds.md
  - Develop:
      - Overview: develop/overview.md
      - Workflows:
          - Github Action: develop/gh-actions.md

mkdocs-public.yml

nav:
  - Home: index.md
  - Tutorial:
      - Overview: tutorial/overview.md
      - Edit this site:
          - Overview: tutorial/this_site/overview.md
          - test tutorial: tutorial/this_site/test_tutorial.md
          - VS Code: tutorial/this_site/vscode.md
          - Markdown: tutorial/this_site/markdown.md
          - Git & GitHub: tutorial/this_site/git.md
  - Simulate:
      - Overview: simulate/overview.md
  - Develop:
      - Overview: develop/overview.md
      # - Workflows:
      #     - Github Action: develop/gh-actions.md

Contributing workflow

This repository is intended as a practice for collaboration with Git and GitHub. Therefore, to contribute to this documentation, you need to follow the steps:

Fork the repository: teoroo-cmc/technicality-private;
Make your contribution by committing to your fork;
Create the pull request, and make changes if requested;
Done!

During the contribution process, you might be asked to clean up the commit history. This means you will need to rebase your work to the upstream. You should also use rebase to combine small fixes like typos in your commits.

If you are assigned as a reviewer for PR, you can check that changes made by it on GitHub. You can also use git checkout to inspect the PR branch and maybe inspect the built documentation after those changes.

Hygiene Rules

If you are editing with VS Code, the LTeX and markdownlint extensions should be installed, they enforce a consistent format for the site, and check for typos. Fix the warnings before committing; if false positives are found, try suppressing them in the setting temporarily, or adding new words to the dictionary. In addition, wrap texts into the 80-character lines whenever reasonable, except for cases like long lines (you can do so with the Alt-q shortcut in VS Code with the Rewrap extension).