Merge pull request #3 from amorison/mkdocs

Migrate documentation to mkdocs

.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - master
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+  pull_request:
+    branches:
+      - master
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: '0'
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+      - run: python3 -m pip install -U pip
+      - run: python3 -m pip install -r docs/requirements.txt
+      - run: python3 -m pip install .
+      - run: mkdocs build --strict -d site
+        env:
+          STAGPY_DOC_CONFIG: 1
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: "site/"
+
+  deploy:
+    needs: build
+    if: ${{ github.event_name == 'workflow_dispatch' || startsWith(github.ref, 'refs/tags/v') }}
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/deploy-pages@v4
+        id: deployment

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018-2022 Adrien Morison
+Copyright (c) 2018 - present Adrien Morison
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.rst → README.md

@@ -1,10 +1,4 @@
-.. image:: https://readthedocs.org/projects/loam/badge/?version=latest
-   :target: http://loam.readthedocs.io/en/latest/?badge=latest
-   :alt: Documentation Status
-
-.. image:: https://badge.fury.io/py/loam.svg
-   :target: https://badge.fury.io/py/loam
-   :alt: PyPI version
+[![PyPI - Version](https://img.shields.io/pypi/v/loam)](https://pypi.org/project/loam/)
 
 loam
 ====

docs/getting-started.md

@@ -0,0 +1,52 @@
+Getting started
+===============
+
+
+Installation
+------------
+
+The loam package is available on PyPI, you can install it with pip:
+
+```sh title="shell"
+python3 -m pip install -U loam
+```
+
+
+Basic usage
+-----------
+
+The following code is a very simple example showing how to use loam to create a
+configuration object with no config file nor argument parsing management.
+
+```py
+from dataclasses import dataclass
+from typing import Optional
+
+from loam.base import entry, Section, ConfigBase
+
+# Dataclasses define the options and their default values.
+@dataclass
+class SectionA(Section):
+    option_a: str = "foo"
+    option_b: int = 42
+    option_c: str = "bar"
+
+# You can attach metadata to each option, such as an explanation
+@dataclass
+class SectionB(Section):
+    option_d: int = entry(val=0, doc="some number")
+    # you can have the same option name living in two different sections
+    option_a: float = entry(val=3.14159, doc="some float")
+
+# A ConfigBase dataclass groups the sections
+@dataclass
+class Config(ConfigBase):
+    section_a: SectionA
+    section_b: SectionB
+
+conf = Config.default_()
+
+# You can access options value and modify them
+assert conf.section_a.option_a == "foo"
+conf.section_b.option_d = 3
+```

docs/index.md

@@ -0,0 +1,3 @@
+{%
+    include-markdown "../README.md"
+%}

docs/requirements.txt

@@ -1,2 +1,7 @@
-sphinx==4.3.0
-sphinx_rtd_theme==1.0.0
+mkdocs~=1.5.3
+mkdocs-gen-files~=0.5.0
+mkdocs-include-markdown-plugin~=6.0.5
+mkdocs-literate-nav~=0.6.1
+mkdocs-material~=9.5.17
+mkdocstrings[python]~=0.24.3
+black~=24.3

loam/_internal.py

@@ -18,8 +18,8 @@
 class Switch(argparse.Action):
     """Inherited from argparse.Action, store True/False to a +/-arg.
 
-    The :func:`switch_opt` function allows you to easily create a
-    :class:`~loam.tools.ConfOpt` using this action.
+    The `switch_opt` function allows you to easily create a
+    [loam.base.Entry] using this action.
     """
 
     def __call__(