Merge pull request #6 from bybatkhuu:develop

Update documentation script

.vscode/settings.json

@@ -28,6 +28,9 @@
 	"[json][jsonc]": {
 		"editor.formatOnSave": true
 	},
+	"[toml]": {
+		"editor.formatOnSave": true
+	},
 	"files.eol": "\n",
 	"files.trimTrailingWhitespace": true,
 	"files.associations": {
@@ -130,7 +133,7 @@
 	},
 	"python.languageServer": "Pylance",
 	"python.analysis.extraPaths": [
-		"${workspaceFolder}/simple_model"
+		"${workspaceFolder}/src"
 	],
 	"yaml.schemas": {
 		"https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"

MANIFEST.in

@@ -0,0 +1,26 @@
+include requirements*.txt
+exclude .github/**
+exclude .vscode/**
+exclude data/**
+exclude docs/**
+exclude examples/**
+exclude models/**
+exclude notebooks/**
+exclude results/**
+exclude scripts/**
+exclude templates/**
+exclude tests/**
+exclude __init__.py
+exclude .editorconfig
+exclude .env.example
+exclude .gitignore
+exclude .gitsubmodules
+exclude .markdownlint.json
+exclude .DS_Store
+exclude CHANGELOG.md
+exclude environment.yml
+exclude Makefile
+exclude MANIFEST.in
+exclude mkdocs.yml
+exclude pytest.ini
+exclude Thumbs.db

Makefile

@@ -0,0 +1,35 @@
+.PHONY: help clean get-version test bump-version build docs example all
+
+help:
+	@echo "make help         -- show this help"
+	@echo "make clean        -- clean leftovers and build files"
+	@echo "make get-version  -- get current version"
+	@echo "make test         -- run tests"
+	@echo "make bump-version -- bump version"
+	@echo "make build        -- build python package"
+	@echo "make docs         -- build documentation"
+	@echo "make example      -- run example script"
+	@echo "make all          -- clean, get-version, test, build"
+
+clean:
+	./scripts/clean.sh $(MAKEFLAGS)
+
+get-version:
+	./scripts/get-version.sh
+
+test:
+	./scripts/test.sh $(MAKEFLAGS)
+
+bump-version:
+	./scripts/bump-version.sh $(MAKEFLAGS)
+
+build:
+	./scripts/build.sh $(MAKEFLAGS)
+
+docs:
+	./scripts/docs.sh $(MAKEFLAGS)
+
+example:
+	python ./examples/simple/main.py
+
+all: clean get-version test build

README.md

@@ -63,9 +63,12 @@ git clone git@github.com:bybatkhuu/model.python-template.git simple_model && \
 > [!NOTE]
 > Choose one of the following methods to install the module **[A ~ E]**:
 
-**A.** Install with **pip** in **editable** mode (for **DEVELOPMENT**):
+**A.** Install with **pip**:
 
 ```sh
+# Install directly from source:
+pip install .
+# Or install with **editable** mode (for **DEVELOPMENT**):
 pip install -e .
 ```
 
@@ -100,24 +103,24 @@ pip install ./simple_model-[VERSION].tar.gz
 
 ```sh
 # Install python dependencies:
-pip install -r requirements.txt
+pip install -r ./requirements.txt
 
 # Copy the module source code into the project:
-cp -r simple_model [PROJECT_DIR]
+cp -r ./src/simple_model [PROJECT_DIR]
 # For example:
-cp -r simple_model /some/path/project/
+cp -r ./src/simple_model /some/path/project/
 ```
 
 **E.** Manually add module path into **PYTHONPATH** (not recommended):
 
 ```sh
 # Add current path to PYTHONPATH:
-export PYTHONPATH="${PWD}:${PYTHONPATH}"
+export PYTHONPATH="${PWD}/src:${PYTHONPATH}"
 
 # Or add the module path to PYTHONPATH:
 export PYTHONPATH="[MODULE_PATH]:${PYTHONPATH}"
 # For example:
-export PYTHONPATH="/some/path/simple_model:${PYTHONPATH}"
+export PYTHONPATH="/some/path/model.python-template/src:${PYTHONPATH}"
 ```
 
 ## Usage/Examples
@@ -197,7 +200,7 @@ if __name__ == "__main__":
 
 ```yaml
 simple_model:                                       # Just an example to group the configs (Not necessary)
-  models_dir: "models"                              # Directory where the models are saved
+  models_dir: "./models"                              # Directory where the models are saved
   model_name: "linear_regression.v0.0.1-240101"     # Name of the model as sub-directory
   threshold: 0.5                                    # Threshold for similarity check
 ```
@@ -217,10 +220,10 @@ To run tests, run the following command:
 
 ```sh
 # Install python test dependencies:
-pip install -r ./requirements/requirements.test.txt
+pip install -r ./requirements.test.txt
 
 # Run tests:
-python -m pytest -sv
+python -m pytest -sv -o log_cli=true
 ```
 
 ## Build Package
@@ -229,7 +232,7 @@ To build the python package, run the following command:
 
 ```sh
 # Install python build dependencies:
-pip install -r ./requirements/requirements.build.txt
+pip install -r ./requirements.build.txt
 
 # Build python package:
 python -m build
@@ -241,7 +244,7 @@ To build the documentation, run the following command:
 
 ```sh
 # Install python documentation dependencies:
-pip install -r ./requirements/requirements.docs.txt
+pip install -r ./requirements.docs.txt
 
 # Serve documentation locally (for development):
 mkdocs serve
@@ -252,7 +255,7 @@ mkdocs build
 ## Documentation
 
 - [Docs](./docs)
-- [Home](./docs/index.md)
+- [Home](./docs/README.md)
 
 ### Getting Started
 
@@ -261,25 +264,42 @@ mkdocs build
 - [Configuration](./docs/pages/getting-started/configuration.md)
 - [Examples](./docs/pages/getting-started/examples.md)
 - [Error Codes](./docs/pages/getting-started/error-codes.md)
-- [File Structure](./docs/pages/getting-started/file-structure.md)
 
-### API Documentation
-
-- [API Reference](./docs/pages/api-docs/index.md)
+### [API Documentation](./docs/pages/api-docs/README.md)
 
 ### Development
 
-- [Test](./docs/pages/dev/test/index.md)
+- [Test](./docs/pages/dev/test.md)
 - [Build](./docs/pages/dev/build.md)
-- [Docs](./docs/pages/dev/docs/index.md)
-- [CI/CD](./docs/pages/dev/cicd/index.md)
-- [Scripts](./docs/pages/dev/scripts/index.md)
+- [Docs](./docs/pages/dev/docs.md)
+- [CI/CD](./docs/pages/dev/cicd.md)
+- [Scripts](./docs/pages/dev/scripts/README.md)
+- [File Structure](./docs/pages/dev/file-structure.md)
 - [Sitemap](./docs/pages/dev/sitemap.md)
+- [Contributing](./docs/pages/dev/contributing.md)
 - [Roadmap](./docs/pages/dev/roadmap.md)
 
+### Research
+
+- [Reports](./docs/pages/research/reports.md)
+- [Benchmarks](./docs/pages/research/benchmarks.md)
+- [References](./docs/pages/research/references.md)
+
+### [Release Notes](./docs/pages/release-notes.md)
+
+### [Blog](./docs/pages/blog/README.md)
+
+### About
+
+- [FAQ](./docs/pages/about/faq.md)
+- [Authors](./docs/pages/about/authors.md)
+- [Contact](./docs/pages/about/contact.md)
+- [License](./docs/pages/about/license.md)
+
 ---
 
 ## References
 
+- <https://scikit-learn.org/stable/modules/generated/sklearn.linear_model.LinearRegression.html>
 - <https://packaging.python.org/en/latest/tutorials/packaging-projects>
 - <https://python-packaging.readthedocs.io/en/latest>

__init__.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
 try:
-    from .simple_model import *
+    from .src.simple_model import *
 except ImportError:
-    from simple_model import *
+    from src.simple_model import *

docs/pages/about/README.md

@@ -0,0 +1,10 @@
+# About
+
+This section contains non-technical information about this project.
+
+## Pages
+
+- [FAQ](./faq.md)
+- [Authors](./authors.md)
+- [Contact](./contact.md)
+- [License](./license.md)

docs/pages/about/authors.md

@@ -1,3 +1,5 @@
 # Authors
 
 This project is developed by the following authors:
+
+- Author 1

docs/pages/about/faq.md

@@ -2,6 +2,6 @@
 
 This section contains frequently asked questions about this project.
 
-## Q1: What is the answer to the Ultimate Question of Life, the Universe, and Everything?
+## Q1: How do I get started with this project?
 
-The answer to the Ultimate Question of Life, the Universe, and Everything is 42.
+To get started with this project, follow the instructions in the [Getting Started](../getting-started/prerequisites.md) guide.

docs/pages/api-docs/ModelConfigPM.md

@@ -0,0 +1,3 @@
+# ModelConfigPM
+
+::: src.simple_model.ModelConfigPM

docs/pages/api-docs/index.md → docs/pages/api-docs/README.md

@@ -1,3 +1,8 @@
 # API Documentation
 
 This section provides information on the API documentation for this project.
+
+## Pages
+
+- [SimpleModel](./SimpleModel.md)
+- [ModelConfigPM](./ModelConfigPM.md)

docs/pages/api-docs/SimpleModel.md

@@ -0,0 +1,3 @@
+# SimpleModel
+
+::: src.simple_model.SimpleModel

docs/pages/dev/index.md → docs/pages/dev/README.md

@@ -8,7 +8,7 @@ This section provides information on how to develop or contribute to this projec
 - [Build](./build.md)
 - [Docs](./docs.md)
 - [CI/CD](./cicd.md)
-- [Scripts](./scripts/index.md)
+- [Scripts](./scripts/README.md)
     - [base.sh](./scripts/1.base.md)
     - [clean.sh](./scripts/2.clean.md)
     - [get-version.sh](./scripts/3.get-version.md)

docs/pages/dev/build.md

@@ -4,7 +4,7 @@ To build the python package, run the following command:
 
 ```sh
 # Install python build dependencies:
-pip install -r ./requirements/requirements.build.txt
+pip install -r ./requirements.build.txt
 
 # Build python package:
 python -m build

docs/pages/dev/docs.md

@@ -4,15 +4,22 @@ To build the documentation, run the following command:
 
 ```sh
 # Install python documentation dependencies:
-pip install -r ./requirements/requirements.docs.txt
+pip install -r ./requirements.docs.txt
 
 # Serve documentation locally (for development):
 mkdocs serve
 # Or build documentation:
 mkdocs build
 ```
 
-## MkDocs
+## MkDocs Material
+
+### Installation
+
+```sh
+# Install mkdocs-material and mkdocstrings:
+pip install -U mkdocs-material mkdocstrings[python]
+```
 
 ### Commands
 
@@ -34,3 +41,4 @@ docs/
 
 - [MkDocs Documentation](https://www.mkdocs.org)
 - [MkDocs Material Documentation](https://squidfunk.github.io/mkdocs-material)
+- [mkdocstrings Documentation](https://mkdocstrings.github.io)

docs/pages/dev/file-structure.md

@@ -38,7 +38,7 @@ project/
 ├── templates/              # Template files (if any, e.g. config files, etc...) used in this project
 ├── tests/                  # Tests for this project
 |   ├── __init__.py             # Initialize the test module
-|   ├── conftest.py             # Configuration for pytest (e.g. fixtures, plugins, pre/post test hooks, etc...)
+|   ├── conftest.py             # Presets for pytest (e.g. fixtures, plugins, pre/post test hooks, etc...)
 |   ├── test_1.py               # Test case files
 |   ├── test_2.py
 |   └── ...
@@ -47,14 +47,16 @@ project/
 ├── .env.example            # Example environment variables file
 ├── .gitignore              # Files and directories to be ignored by git (e.g. data, models, results, etc...)
 ├── .markdownlint.json      # Markdown linting rules
-├── .environment.yml        # Conda environment file
+├── CHANGELOG.md            # List of changes for each version of the project
+├── environment.yml         # Conda environment file
 ├── LICENSE.txt             # License file for this project
 ├── Makefile                # Makefile for common commands and automation
+├── MANIFEST.in             # Manifest file for setuptools (to include/exclude files in the source distribution)
 ├── mkdocs.yml              # MkDocs configuration file
 ├── pyproject.toml          # PEP 518 configuration file for python packaging
 ├── pytest.ini              # Pytest configuration file
 ├── README.md               # Main README file for this project
 ├── requirements.txt        # Main python dependency requirements for this project
 ├── setup.cfg               # Configuration for setuptools
-└── setup.py                # Setup script for setuptools (old way of packaging)
+└── setup.py                # Setup script for setuptools (for backward compatibility)
 ```

docs/pages/dev/scripts/7.docs.md

@@ -0,0 +1,22 @@
+# docs.sh
+
+This script is used to manage the documentation for the project, providing options to either serve a local documentation server or build the documentation as static HTML files.
+
+The script performs the following operations:
+
+- **Loading base script**: Includes the `base.sh` script to gain access to its utility functions and environment variables.
+- **Serving documentation**: If no flags are set, runs `mkdocs serve` to start a local documentation server for live preview.
+- **Building documentation**: If the `-b` or `--build` flag is set, the script builds the documentation as static HTML files using `mkdocs build`, placing the output in the `site` directory.
+
+**Usage**:
+
+To execute the documentation script, use the following command in the terminal:
+
+```sh
+./docs.sh [-b|--build]
+```
+
+**Examples**:
+
+- To serve the documentation: `./docs.sh`
+- To build the documentation: `./docs.sh -b`

docs/pages/dev/scripts/index.md → docs/pages/dev/scripts/README.md

@@ -8,6 +8,7 @@ This document provides an overview and usage instructions for the following scri
 - [**`test.sh`**](./4.test.md)
 - [**`bump-version.sh`**](./5.bump-version.md)
 - [**`build.sh`**](./6.build.md)
+- [**`docs.sh`**](./7.docs.md)
 
 All the scripts are located in the **`scripts`** directory:
 
@@ -17,6 +18,7 @@ scripts/
 ├── build.sh
 ├── bump-version.sh
 ├── clean.sh
+├── docs.sh
 ├── get-version.sh
 └── test.sh
 ```