docs: adjust documentation to include markdown

.github/workflows/documentation.yml

@@ -8,12 +8,23 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-python@v3
-      - name: Install sphinx
-        run: |
-          pip install sphinx sphinx_rtd_theme
+      - name: Install poetry
+        uses: abatilo/actions-poetry@v2.3.0
       - name: Install dependencies
+        run: poetry install --no-root
+      - name: Setup a local virtual environment for caching
         run: |
-          pip install -r requirements.txt
+          poetry config virtualenvs.create true --local
+          poetry config virtualenvs.in-project true --local
+      - name: Define a cache for the virtual environment based on the dependencies lock file to speed up later runs
+        uses: actions/cache@v3
+        with:
+          path: ./.venv
+          key: venv-${{ hashFiles('poetry.lock') }}
+      - name: Install sphinx
+        run: pip install sphinx sphinx_rtd_theme
+      - name: Install myst-parser
+        run: pip install myst-parser
       - name: Sphinx build
         run: |
           sphinx-build docs _build

docs/businesstrips.rst

@@ -4,7 +4,7 @@ Business trips
 
 .. toctree::
    :maxdepth: 2
-   :caption: toc
+   :caption: See also:
    :titlesonly:
    :includehidden:
 

docs/conf.py

@@ -23,8 +23,10 @@
 # -- Project information -----------------------------------------------------
 
 project = "co2calculator"
-copyright = "2022, Christina Ludwig, Veit Ulrich, Hannah Weiser"
-author = "Christina Ludwig, Veit Ulrich, Hannah Weiser"
+copyright = (
+    "2024, Christina Ludwig, Veit Ulrich, Hannah Weiser, Sarah Lohr, Fabian Kneissl"
+)
+author = "Christina Ludwig, Veit Ulrich, Hannah Weiser, Sarah Lohr, Fabian Kneissl"
 
 # The full version, including alpha/beta/rc tags
 release = "0.1.0"
@@ -41,6 +43,7 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.viewcode",
+    "myst_parser",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/documentation.md

@@ -1,4 +1,4 @@
-# Documentation of CO<sub>2</sub> calculations
+# Methodology
 
 The *co2calculator* can compute emissions caused by four big areas of the work life: Electricity, Heating, Business trips and Commuting. Emissions are given as CO<sub>2</sub> equivalents (CO<sub>2</sub>e). 
 

docs/index.rst

@@ -9,20 +9,21 @@ Welcome to co2calculator's documentation!
 **co2calculator** is a Python package to calculate work related CO2 emissions from heating and electricity consumption as well as business trips and commuting.
 
 
-.. note::
+Contents
+==================
 
-   This project is under active development.
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
    :titlesonly:
    :includehidden:
 
-   calculate/heating_electricity
+   documentation
    businesstrips
    commuting
+   calculate/heating_electricity
    calculate/emission_factors
+   calculate/transport_modes
 
 
 Indices and tables

pyproject.toml

@@ -14,15 +14,18 @@ pydantic = "1.9.0"
 iso3166 = "^2.1.1"
 python-dotenv = "^1.0.1"
 thefuzz = "^0.22.1"
+myst-parser = "^3.0.1"
 
 [tool.poetry.group.dev.dependencies]
 pre-commit = "^3.7.0"
 pytest = "^8.2.0"
 pytest-mock = "^3.14.0"
 pytest-cov = "^5.0.0"
 pygments = "^2.17.2"
-Sphinx = "^7.3.7"
+sphinx = "^7.3.7"
 sphinx-toolbox = "^3.5.0"
+sphinx_rtd_theme = "^1.0.0"
+myst-parser = "^3.0.1"
 
 [build-system]
 requires = ["poetry-core"]