readme.md

Amuzil Docs

The documentation for all Amuzil projects, open source so all can contribute.
Check it out »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Why open source the documentation?
   • Built with
2. Getting Started
   • Prerequisites
   • Installation
3. Contributing
4. License
5. Contact
6. Acknowledgments

About The Project

The Amuzil Docs is a documentation site for all Amuzil projects. It is and will probably always be a work in progress, as we are always adding new features to our projects. The documentation is made with Material for MkDocs, a Material Design theme for MkDocs.

(back to top)

Why open source the documentation?

We believe that open source is the future, and that everyone should be able to contribute to the projects they use. Documentation is a very important part of any project; a project is useless if no one knows how to use it. By open sourcing the documentation, we hope to achieve the following:

• Better documentation: The documentation is written by the community, for the community. The community will write much better documentation than a small team of developers, as they are the end users of the documentation.
• More contributors: By open sourcing the documentation, we hope to attract more contributors to the project. Contributors can help us improve the documentation, and they can also help us improve the projects themselves.
• Reduced workload: By open sourcing the documentation, we hope to reduce the workload of the developers. The developers can focus on developing the projects, and the community can focus on improving the documentation.
• Open Source: Open source is one of the core pillars of our community. We believe that everyone should be able to contribute to the projects they use, so that they can improve it and learn from it.
• Community: We want to build a community around our projects, and open sourcing the documentation is a great way to do that. It gives active contributors a sense of ownership, and it gives people a reason and way to contribute without necessitating technical knowledge or skills.

(back to top)

Built with

(back to top)

Getting started

This guide is not yet finalised and may not be complete. It is also not yet tested.

Prerequisites

Before you begin, ensure you have met the following requirements:

• Python 3

  • To check if you have Python installed, run the following command:

    python --version

    It should return a version number, such as 3.11.0. Ensure that the version number is 3.

• Node.js / (We recommend using NVM (Linux/macOS / Windows) to install Node.js)

  • To check if you have Node.js installed, run the following command:

    node --version

    It should return a version number, such as 18.11.0. Ensure that the version number is at least 18.

• PNPM

  • To check if you have PNPM installed, run the following command:

    pnpm --version

    It should return a version number, such as 7.14.2. Ensure that the version number is at least 7.

• Git

  • To check if you have Git installed, run the following command:

    git --version

    It should return a version number, such as 2.33.0. Ensure that the version number is at least 2.

• (Windows only) GTK+

Installation

While the below guide details specific git commands, you also can (and probably should) use a GUI for Git. Options include any JetBrains IDE ( such as IntelliJ IDEA) , GitHub Desktop, or GitKraken.

1. Clone the repo

   git clone https://github.com/amuzil/docs.git

2. Create a Python virtual environment and activate it

   # All platforms
   python -m venv venv
   # Linux/macOS
   source venv/bin/activate
   # Windows
   venv\Scripts\activate

3. Install the dependencies

   pnpm install

4. Serve the live preview

   pnpm serve

This will start a live preview of the site. You can access it at http://localhost:8000.

(back to top)

Installation (Insiders)

If you have access to the Insiders version of Material for MkDocs, the installation process is slightly different.

1. Clone the repo

   git clone https://github.com/amuzil/docs.git

2. Create a .env file and set your Insiders access token

   MKDOCS_MATERIAL_INSIDERS_TOKEN={YOUR_TOKEN}

3. Create a Python virtual environment and activate it

   # All platforms
   python -m venv venv
   # Linux/macOS
   source venv/bin/activate
   # Windows
   venv\Scripts\activate

4. (Windows only) Install LXML binaries

   1. Download the latest (CPython) Wheel file to your venv/Lib folder

   2. Run the following command:

      pip install venv\Lib\{WHEEL_FILE}

5. Install the dependencies

   pnpm install
   # Remember to replace {YOUR_TOKEN} with your actual token
   pip install git+https://{YOUR_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git

6. Serve the live preview

   pnpm serve:insiders

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue. If you really like the project, consider giving it a star!

We use Gitmoji, which is an emoji guide for Git commit messages. It makes it easier to see what kind of changes have been made at a glance.

To make things easier, check out Gitmoji Plus: Commit Button, a plugin for JetBrains IDEs that adds a button to the commit dialog that allows you to easily add a Gitmoji to your commit message.

While the below guide details specific git commands, you also can (and probably should) use a GUI for Git. Options include any JetBrains IDE (such as IntelliJ IDEA), GitHub Desktop, or GitKraken.

1. Fork the Project

2. Create your Feature Branch

   git checkout -b feature/amazing-feature

   Branch naming guidelines:

   • Prefix your branch with the topic. Use lowercase branch names. Replace spaces with hyphens.
   • If you are working on a page in the documentation, prefix your branch with the project that page belongs to. For example, if you are working on Magus's installation.md page, your branch would be magus/installation. If you are working on a page that does not belong to a specific project, prefix it with docs.
   • If you are working on a blog post, prefix your branch with blog.
   • If you are working on anything else, use feature, or something else if applicable (devcontainer, ci, etc.).

3. Commit your Changes

   git commit -m ":sparkles: Add some amazing feature"

4. Push to the Branch

   git push origin feature/amazing-feature

5. Open a Pull Request

(back to top)

License

Distributed under the Unlicense. See license.md for more information.

(back to top)

Contact

Main contact: Luka "Mahtaran" Leer

(back to top)

Acknowledgments

• Readme template by Othneil Drew

(back to top)