Python Project Template with MkDocs

This project is a template for creating Python projects with documentation generated using MkDocs. It provides a standard project structure, a sample requirements.txt for dependencies, and configurations for generating documentation in a simple, beautiful, and accessible format.

.

Features

• Organized Python Project Structure: Includes docs/ directory for markdown documentation files.
• MkDocs Integration: Easily create and serve project documentation locally or deploy to GitHub Pages.
• Dependency Management: Use requirements.txt for managing project dependencies.
• Sample Scripts: Helpful Bash scripts for managing virtual environments and installing dependencies.

Getting Started

Prerequisites

Make sure you have the following installed:

• Python 3.6+

Project Structure

.
|── .github
|   |── workflows        # Github actions scripts
|   |── ...
|── docs/                # MkDocs documentation files
|   |── res              # Ressources (images, etc...) for the documentation
|   |── stylesheets      # Custom CSS theme for your documentation
|   |── index.md         # Home page for the documentation
|   |── ...              # Additional documentation files
|── scripts              # Scripts to generate the venv and deploy locally
|── requirements.txt     # Python dependencies
|── mkdocs.yml           # MkDocs configuration file
.

Installation

1. Clone the repository:

   git clone https://github.com/username/repo-name.git
   cd repo-name

2. Create a virtual environment, installs dependencies (recommended):

   sh scripts/venv.sh make

Usage

Running the Project

You can place your documentation files in the docs/ directory and use it as your primary documentation location. Each new markdown file has to be registered in the mdkocs.yml file (see mkdocs documentation).

Building and Serving Documentation

1. Build the documentation:

   mkdocs build

   or

   sh scripts/build_static.sh

   This will generate static HTML files in the site/ directory.

2. Serve documentation locally:

   mkdocs serve

   or

   sh scripts/deploy_locally.sh

   Navigate to http://127.0.0.1:8000 in your browser to view the documentation.

Deploying Documentation to GitHub Pages

• Push to the main branch and let the magic happen 😊.

Configuration

Customize the MkDocs configuration by editing mkdocs.yml. Here you can change the site name, theme, navigation, and more.

Contributing

If you want to contribute to this project template:

1. Fork the repository.
2. Create a new branch (git checkout -b feature/YourFeature).
3. Make your changes.
4. Push your branch (git push origin feature/YourFeature).
5. Open a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.