From b109578ec1e8635aeb9f12c3a913108232347935 Mon Sep 17 00:00:00 2001 From: Théo de la Hogue Date: Tue, 6 Jun 2023 17:46:24 +0200 Subject: Working on documentation architecture. --- docs/contributor_guide/build_documentation.md | 23 +++++++ docs/contributor_guide/unitary_test.md | 33 ++++++++++ docs/css/extra.css | 27 +++++++- docs/getting_started.md | 89 -------------------------- docs/getting_started/demos.md | 8 +++ docs/getting_started/installation.md | 31 +++++++++ docs/getting_started/ready-made.md | 8 +++ docs/logo-large.png | Bin 0 -> 31216 bytes docs/requirements.in | 1 + docs/user_guide/ar_environment_axis.png | Bin 0 -> 106367 bytes 10 files changed, 130 insertions(+), 90 deletions(-) create mode 100644 docs/contributor_guide/build_documentation.md create mode 100644 docs/contributor_guide/unitary_test.md delete mode 100644 docs/getting_started.md create mode 100644 docs/getting_started/demos.md create mode 100644 docs/getting_started/installation.md create mode 100644 docs/getting_started/ready-made.md create mode 100644 docs/logo-large.png create mode 100644 docs/user_guide/ar_environment_axis.png diff --git a/docs/contributor_guide/build_documentation.md b/docs/contributor_guide/build_documentation.md new file mode 100644 index 0000000..20df1df --- /dev/null +++ b/docs/contributor_guide/build_documentation.md @@ -0,0 +1,23 @@ +Build documentation +=================== + +ArGaze has a standard MkDocs layout which is built by Read the Docs. You can build and view this documentation project locally. + +!!! note + + *Consider that all inline commands below have to be executed into ArGaze root folder.* + +Install required Python dependencies (MkDocs etc.): +```console +pip install -r docs/requirements.in +``` + +Run the mkdocs development server: +```console +mkdocs serve +``` + +Export the mkdocs site: +```console +mkdocs build +``` diff --git a/docs/contributor_guide/unitary_test.md b/docs/contributor_guide/unitary_test.md new file mode 100644 index 0000000..42cf24c --- /dev/null +++ b/docs/contributor_guide/unitary_test.md @@ -0,0 +1,33 @@ +Unitary test +============ + +ArGaze package unitary tests are based on [unittest](https://docs.python.org/fr/3.10/library/unittest.html) module. +Test files tree structure is mirroring the file tree structure of src/argaze folder. + +!!! note + + *Consider that all inline commands below have to be executed into ArGaze root folder.* + + +To run all unitary tests: + +```shell +python -m unittest discover ./src/argaze.test "*.py" +``` + +To run only submodule unitary tests: + +```shell +python -m unittest discover ./src/argaze.test/SUBMODULE "*.py" +``` + +To run only a single unitary test file from a submodule: + +```shell +python -m unittest discover ./src/argaze.test/SUBMODULE/ TEST_FILE.py +``` + +!!! note + + **Verbose mode** + *Use -v option to get more details.* diff --git a/docs/css/extra.css b/docs/css/extra.css index 0639582..32bb71d 100644 --- a/docs/css/extra.css +++ b/docs/css/extra.css @@ -1 +1,26 @@ -.rst-content code {color: #404040;} +.wy-side-nav-search { + background: #0299D2; +} + +.caption-text { + color: #0299D2; +} + +.wy-nav-content { + max-width: 100%; +} + +.doc > code {color: #0299D2; background: none; border: 0px; font-size: 100%; padding: 0;} +.doc-contents {margin: 0px 0px 0px 1%;} + +.doc-module > code {color: #404040;} +.doc-class > code {color: #0299D2;} +.doc-function > code {color: #0299D2;} +.docutils code, a {color: dimgray;} +.docutils th, p {color: dimgray;} + +.doc-label > code {border: 0px; border-radius: 15px; padding: 2px 8px; font-weight: bold; color: white;} + +.doc-label-dataclass > code {background: none; color: dimgray;} +.doc-label-classmethod > code {background: none; color: dimgray;} +.doc-label-property > code {background: none; color: dimgray;} \ No newline at end of file diff --git a/docs/getting_started.md b/docs/getting_started.md deleted file mode 100644 index 4951a25..0000000 --- a/docs/getting_started.md +++ /dev/null @@ -1,89 +0,0 @@ -Getting started -===== -Here are all you need to deal with ArGaze library. - -!!! note - - *Consider that all inline commands below have to be executed into ArGaze root folder.* - -Installation ------------- - -Install build tool package: - -```console -pip install build -``` - -Then, build ArGaze package: -```console -python -m build -``` - -Then, install ArGaze package (replace VERSION by what has been built into dist folder): -```console -pip install ./dist/argaze-VERSION.whl -``` - -!!! note - - **As Argaze library developper** - *You should prefer to install the package in developer mode to test live code changes:* - - ``` - pip install -e . - ``` - -Documentation ------------- - -ArGaze has a standard MkDocs layout which is built by Read the Docs. You can build and view this documentation project locally. - -Install required Python dependencies (MkDocs etc.): -```console -pip install -r docs/requirements.in -``` - -Run the mkdocs development server: -```console -mkdocs serve -``` - -Export the mkdocs site: -```console -mkdocs build -``` - -## Cookbook - -The `argaze.utils` submodule is a good place to get ready made code examples. - - -Test ------------- - -ArGaze package unitary tests are based on [unittest](https://docs.python.org/fr/3.10/library/unittest.html) module. -Test files tree structure is mirroring the file tree structure of src/argaze folder. - -To run all unitary tests: - -```shell -python -m unittest discover ./src/argaze.test "*.py" -``` - -To run only submodule unitary tests: - -```shell -python -m unittest discover ./src/argaze.test/SUBMODULE "*.py" -``` - -To run only a single unitary test file from a submodule: - -```shell -python -m unittest discover ./src/argaze.test/SUBMODULE/ TEST_FILE.py -``` - -!!! note - - **Verbose mode** - *Use -v option to get more details.* diff --git a/docs/getting_started/demos.md b/docs/getting_started/demos.md new file mode 100644 index 0000000..1a53c82 --- /dev/null +++ b/docs/getting_started/demos.md @@ -0,0 +1,8 @@ +Demonstration scripts +===================== + +{% + include-markdown "../../src/argaze/utils/README.md" + start="" + end="" +%} diff --git a/docs/getting_started/installation.md b/docs/getting_started/installation.md new file mode 100644 index 0000000..327e79a --- /dev/null +++ b/docs/getting_started/installation.md @@ -0,0 +1,31 @@ +Install ArGaze +============== + +!!! note + + *Consider that all inline commands below have to be executed into ArGaze root folder.* + +Install build tool package: + +```console +pip install build +``` + +Then, build ArGaze package: +```console +python -m build +``` + +Then, install ArGaze package (replace VERSION by what has been built into dist folder): +```console +pip install ./dist/argaze-VERSION.whl +``` + +!!! note + + **As Argaze library developper** + *You should prefer to install the package in developer mode to test live code changes:* + + ``` + pip install -e . + ``` diff --git a/docs/getting_started/ready-made.md b/docs/getting_started/ready-made.md new file mode 100644 index 0000000..32c475c --- /dev/null +++ b/docs/getting_started/ready-made.md @@ -0,0 +1,8 @@ +Ready-made scripts +================== + +{% + include-markdown "../../src/argaze/utils/README.md" + start="" + end="" +%} diff --git a/docs/logo-large.png b/docs/logo-large.png new file mode 100644 index 0000000..cf0a214 Binary files /dev/null and b/docs/logo-large.png differ diff --git a/docs/requirements.in b/docs/requirements.in index bec300c..647ae23 100644 --- a/docs/requirements.in +++ b/docs/requirements.in @@ -1,3 +1,4 @@ mkdocs mkdocstrings[python] markdown-include +mkdocs-include-markdown-plugin diff --git a/docs/user_guide/ar_environment_axis.png b/docs/user_guide/ar_environment_axis.png new file mode 100644 index 0000000..01c1791 Binary files /dev/null and b/docs/user_guide/ar_environment_axis.png differ -- cgit v1.1