diff --git a/.gitignore b/.gitignore index dc71ab2..3d68b75 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ site/ .idea/ +.DS_Store diff --git a/docs/en/contributing/contributing-to-docs.md b/docs/en/contributing/contributing-to-docs.md index 81a4161..16c6496 100644 --- a/docs/en/contributing/contributing-to-docs.md +++ b/docs/en/contributing/contributing-to-docs.md @@ -1,28 +1,236 @@ # Contributing to documentation -We use [MkDocs](https://www.mkdocs.org/) and [Github pages](https://pages.github.com/) for the documentation site you're reading right now. +This guide walks you through contributing to this documentation site, which is powered by [MkDocs](https://www.mkdocs.org/) and [GitHub pages](https://pages.github.com/). -## Prerequisites +## Step 0: Prerequisites -Before you begin, ensure you have the following installed on your system: +Before you start, make sure you have the following installed on your system: -- **Python 3** - Required for MkDocs -- **pip** - Python package installer (usually comes with Python) +### Git -Check [MkDocs' installation guide](https://www.mkdocs.org/user-guide/installation/) on how to install these dependencies. +Git is required to clone the repository and manage your changes. -## How to get started +You can use [Git](https://git-scm.com/install/) from a command line interface, or use GUI such as [GitHub Desktop](https://desktop.github.com/download/) (recommended). -1. Clone the `pylon-docs` repository: `git clone https://github.com/pylonmc/pylon-docs` -2. Install all required dependencies: `pip install -r requirements.txt` -3. Run the documentation website locally using `mkdocs serve` +### GitHub Account -## Deploying +You will need a GitHub account to fork the repository and create pull requests. -Only core members can deploy the website. +If you don't have an account yet, you can [create one for free](https://github.com/signup). -1. Clone the `pylonmc.github.io` repository: `git clone https://github.com/pylonmc/pylonmc.github.io` -2. Deploy the site by running **in the pylonmc.github.io repository** `mkdocs gh-deploy --config-file ../pylon-docs/mkdocs.yml --remote-branch master` +### Python and pip -[comment]: <> (TODO add more detailed explanation like Slimefun has (https://github.com/Slimefun/Slimefun4/wiki/Expanding-the-Wiki)) +MkDocs requires a recent version of [Python](https://www.python.org/), and the package manager [pip](https://pip.pypa.io/en/stable/installation/), to be installed on your system. +You can check if you already have these installed from the command line (versions may be different): + +```bash +$ python3 --version +Python 3.13.3 +$ pip3 --version +pip 25.2 +``` + +If Python is not installed, you can download it from the [official Python downloads page](https://www.python.org/downloads/). + +!!! note "For Windows users" + During installation, make sure to check the box that says "Add Python to PATH" if the installer offers such an option (it's usually off by default). + + ![Add Python to PATH](img/python-windows-path.png) + +--- + +## Step 1: Forking the repository + +Now head over to the [pylon-docs repository](https://github.com/pylonmc/pylon-docs). +Click the "Fork" button in the top-right corner of the page to create your own copy of the repository. + +![GitHub Fork](img/github-fork.png) + +--- + +## Step 2: Cloning your fork + +You will need to clone your forked repository to your local machine to be able to preview the changes. + +If you use GitHub Desktop, follow [these steps](https://docs.github.com/en/desktop/adding-and-cloning-repositories/cloning-a-repository-from-github-to-github-desktop). + +If you use command line, go to your forked repository on GitHub and click the green "Code" button to copy the HTTPS URL. + +![GitHub Clone URL](img/github-clone.png) + +Then, execute the following command: + +```bash +git clone +``` + +--- + +## Step 3: Installing dependencies + +Now that you have the repository on your local machine, you need to install the required dependencies. + +In the `pylon-docs` directory, run: + +```bash +pip install -r requirements.txt +``` + +This will install MkDocs and all other necessary packages. + +--- + +## Step 4: Making your changes + +Now you can start editing the documentation files! + +!!! warning + All changes you make to your fork will NOT affect the official documentation until you submit your changes via a pull request. + +The documentation files are written in Markdown. If you need help with the syntax, you can consult [Mastering Markdown](https://guides.github.com/features/mastering-markdown/) or review [the Markdown file for this page](https://github.com/pylonmc/pylon-docs/blob/main/docs/en/contributing/contributing-to-docs.md?plain=1). + +### 4.1 Understanding the documentation structure + +The documentation is organized by language in the `docs/` directory: + +```text +docs/ +├── en/ # English documentation +├── zh-CN/ # Simplified Chinese documentation +└── ... # Other languages +``` + +For English documentation, all pages are located in `docs/en/`. The content is organized into different sections and subdirectories. + +!!! danger "Important" + Currently, we only accept contributions to the English documentation, as we are still actively working on the content of Pylon. Please stay tuned for future updates regarding contributions to other languages. + +Each section has its own directory, and images for that section should be placed in an `img/` folder within the same directory. + +### 4.2 Creating a new page + +Open your code editor in the `pylon-docs` directory and follow these steps: + +1. Navigate to the appropriate subdirectory in `docs/en/` (e.g., `docs/en/installation/`) +2. Create a new `.md` file with a descriptive name + +**File naming rules:** + +- File names must end with `.md` +- Use lowercase letters +- Use hyphens `-` instead of spaces +- No special characters +- Examples: `installing-addons.md`, `custom-recipes.md`, `getting-started.md` + +Then: + +1. Write your content using [Markdown syntax](https://guides.github.com/features/mastering-markdown/) +2. Save the file +3. Preview your changes (see [Step 5](#step-5-previewing-your-changes)) + +### 4.3 Editing an existing page + +1. Open the file you want to edit in your code editor +2. Make your changes +3. Save the file +4. Preview your changes (see [Step 5](#step-5-previewing-your-changes)) + +### 4.4 Adding images + +#### Image naming conventions + +- Use lowercase letters only +- Use hyphens `-` instead of spaces +- Use descriptive names +- Use PNG format when possible +- Examples: `github-fork.png`, `custom-item-example.png`, `crafting-table.png` + +#### Where to place images + +Images should be placed in an `img/` folder **in the same directory** as your markdown file. + +For example: + +- If your page is `docs/en/installation/installing-pylon.md` +- Place images in `docs/en/installation/img/` + +If the `img/` folder doesn't exist in that directory, create it first. + +#### Using images in your page + +To embed an image in your markdown file, use the following syntax: + +```markdown +![Image description](img/your-image-name.png) +``` + +**Example:** + +```markdown +![GitHub Fork button](img/github-fork.png) +``` + +--- + +## Step 5: Previewing your changes + +Before submitting your changes, it's a good idea to preview them locally to make sure everything looks correct. + +Run the following command in the `pylon-docs` directory: + +```bash +mkdocs serve --livereload +``` + +This will start a local web server. Open your browser and go to [`http://127.0.0.1:8000`](http://127.0.0.1:8000) to see the documentation site with your changes. + +The preview will automatically update when you save changes to the files. + +--- + +## Step 6: Committing and pushing your changes + +Once you're happy with your changes, you need to commit and push them to your fork. + +If you use GitHub Desktop, follow [these steps](https://docs.github.com/en/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop) to proceed. + +If you use command line, run the following commands in the `pylon-docs` directory: + +```bash +git add . +git commit -m "Your commit message describing the changes" +git push +``` + +!!! tip + Write a clear and descriptive commit message that explains what you changed and why. + +--- + +## Step 7: Creating a pull request + +Once you pushed your changes to your fork on GitHub, you can create a pull request to submit your changes. + +1. Go to your forked repository on GitHub. You can always find your fork on GitHub's dashboard or your profile page. +2. Click on the "Pull requests" tab. +![GitHub Pull Requests Tab](img/github-pull-requests.png) +3. Click on the green "New pull request" button. +4. Fill in the title and description for your pull request. +5. Click "Create pull request". + +That's it! Your changes will be reviewed by the maintainers. If everything looks good, your contribution will be accepted. + +--- + +## Step 8: Making changes to your Pull Request + +If you have already submitted a pull request but need to make changes (for example, if a reviewer requested changes), you can do that easily. + +Just repeat [Step 4](#step-4-making-your-changes) through [Step 6](#step-6-committing-and-pushing-your-changes) to make and commit your changes. + +The pull request will automatically update to include your new changes until it has been merged or closed. + +--- + +**Thank you for contributing to the Pylon documentation!** diff --git a/docs/en/contributing/img/github-clone.png b/docs/en/contributing/img/github-clone.png new file mode 100644 index 0000000..404662e Binary files /dev/null and b/docs/en/contributing/img/github-clone.png differ diff --git a/docs/en/contributing/img/github-fork.png b/docs/en/contributing/img/github-fork.png new file mode 100644 index 0000000..da69b1a Binary files /dev/null and b/docs/en/contributing/img/github-fork.png differ diff --git a/docs/en/contributing/img/github-pull-requests.png b/docs/en/contributing/img/github-pull-requests.png new file mode 100644 index 0000000..cf6cfec Binary files /dev/null and b/docs/en/contributing/img/github-pull-requests.png differ diff --git a/docs/en/contributing/img/python-windows-path.png b/docs/en/contributing/img/python-windows-path.png new file mode 100644 index 0000000..7cdfd86 Binary files /dev/null and b/docs/en/contributing/img/python-windows-path.png differ