Skip to content

Update documentation contributing guide (14) #916

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Andriciuc wants to merge 1 commit into
base: 14
Choose a base branch
from
Open

Update documentation contributing guide (14) #916

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
184 changes: 72 additions & 112 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,201 +1,161 @@
# Documentation contributing guide

# Contributing Guide
This guide explains how to contribute to the Percona Distribution for PostgreSQL documentation.

Thank you for deciding to contribute and help us improve Percona Distribution for PostgreSQL documentation!
We welcome contributors from all users and the community. By contributing, you agree to the [Percona Community code of conduct](https://github.com/percona/community/blob/main/content/contribute/coc.md).

We welcome contributors from all users and community. By contributing, you agree to the [Percona Community code of conduct :octicons-link-external-16: :octicons-link-external-16:](httpss://github.com/percona/community/blob/main/content/contribute/coc.md).
If you want to contribute code, see the [Code contribution guide](https://github.com/percona/postgres/blob/PSP_REL_18_STABLE/.github/CONTRIBUTING.md).

<<<<<<< HEAD
This repository contains the source file for `pg_stat_monitor` documentation and this document explains how you can contribute to it.
=======
You can contribute to documentation in the following ways:

1. **Request a doc change through a Jira issue**. If you’ve spotted a doc issue (a typo, broken links, inaccurate instructions, etc.) but don’t have time nor desire to fix it yourself - let us know about it.
1. Request documentation changes through Jira:

- Click the **Submit DOC bug** link on the sidebar. This opens the [Jira issue tracker :octicons-link-external-16: :octicons-link-external-16:](httpss://jira.percona.com/projects/DISTPG/issues) for the doc project.
- Sign in (create a Jira account if you don’t have one) and click **Create** to create an issue.
- Describe the issue you have detected in the Summary, Description, Steps To Reproduce, Affects Version fields.
- Open the [Jira issue tracker](https://jira.percona.com/projects/PG/issues) for the project.
- Sign in (create a Jira account if you don’t have one).
- Click **Create** to create an issue.
- (Optional but recommended) Search if the issue you want to report is already reported.
- Select **PostgreSQL PG** in the Project dropdown and the work type.
- Describe the issue in the Summary and Description fields. Optionally, you can also fill in the Steps To Reproduce and Affects Version fields.

2. **[Contribute to documentation yourself](#contribute-to-documentation-yourself)**. There is the **Edit this page** link that leads you to the source file of the page on GitHub. There you make changes, create a pull request that we review and add to the doc project. For details how to do it, read on.
>>>>>>> 9ee26788... Restructured docs
2. [Contribute to documentation on GitHub](#contribute-directly-on-github).

## Contribute to documentation
To contribute to the documentation, basic familiarity with the following tools is useful:

Percona Distribution for PostgreSQL documentation is written in [Markdown :octicons-link-external-16:](httpss://www.markdownguide.org/basic-syntax/) language, so you can
[edit it online via GitHub](#edit-documentation-online-vi-github). If you wish to have more control over the doc process, jump to how to [edit documentation locally](#edit-documentation-locally).
- [Markdown](https://www.markdownguide.org/basic-syntax/). The documentation is written in Markdown.
- [MkDocs](https://www.mkdocs.org/getting-started/) documentation generator. We use it to convert source ``.md`` files to html and PDF documents.
- [git](https://git-scm.com/) and [GitHub](https://guides.github.com/activities/hello-world/)

To contribute to the documentation, you should be familiar with the following technologies:
<<<<<<< HEAD
## Contribute directly on GitHub

- [MkDocs :octicons-link-external-16:](httpss://www.mkdocs.org/getting-started/) documentation generator. We use it to convert source ``.md`` files to .html and PDF documents.
- [git :octicons-link-external-16:](httpss://git-scm.com/) and [GitHub :octicons-link-external-16:](httpss://guides.github.com/activities/hello-world/)
- [Docker :octicons-link-external-16:](httpss://docs.docker.com/get-docker/). It allows you to run MkDocs in a virtual environment instead of installing it and its dependencies on your machine.
=======
- [Markdown :octicons-link-external-16: :octicons-link-external-16:](httpss://www.markdownguide.org/basic-syntax/) markup language. It is used to write the documentation.
- [MkDocs :octicons-link-external-16: :octicons-link-external-16:](httpss://www.mkdocs.org/getting-started/) documentation generator. We use it to convert source ``.md`` files to html and PDF documents.
- [git :octicons-link-external-16: :octicons-link-external-16:](httpss://git-scm.com/) and [GitHub :octicons-link-external-16: :octicons-link-external-16:](httpss://guides.github.com/activities/hello-world/)
- [Docker :octicons-link-external-16: :octicons-link-external-16:](httpss://docs.docker.com/get-docker/). It allows you to run MkDocs in a virtual environment instead of installing it and its dependencies on your machine.
>>>>>>> 9ee26788... Restructured docs
There are several active versions of the documentation. Each version derives from the major version of PostgreSQL, included in the distribution.

There are several active versions of the documentation. Each version derives from the major version of PostgreSQL, included in the distribution.
Each documentation branch is named after the PostgreSQL major version (for example: `11`(EOL), `12`(EOL), `13`(EOL), `14`, `15`, `16`, `17`, `18`).

Each version has a branch in the repository named accordingly:
The source .md files are in the ``postgresql-docs/docs`` directory.

- 11 (EOL)
- 12 (EOL)
- 13
- 14
- 15
<<<<<<< HEAD
=======
- 16
- 17
>>>>>>> 5059c6e7... Tested a new PDF generation plugin
To start contributing:

The source .md files are in the ``docs`` directory.
1. Select **Edit this file**.

### Edit documentation online via GitHub
> **NOTE**
> If you haven’t worked with the repository before, GitHub creates a [fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of it for you.

<<<<<<< HEAD
1. Click the **Edit this page** icon next to the page title. The Markdown file of the page opens in GitHub editor in your browser. If you haven’t worked with the repository before, GitHub creates a [fork :octicons-link-external-16:](httpss://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of it for you.
=======
1. Click the **Edit this page** link on the sidebar. The Markdown file of the page opens in GitHub editor in your browser. If you haven’t worked with the repository before, GitHub creates a [fork :octicons-link-external-16: :octicons-link-external-16:](httpss://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of it for you.
>>>>>>> 9ee26788... Restructured docs

2. Edit the page. You can check your changes on the **Preview** tab.
2. Add your changes. You can see how your edit looks in the **Preview** tab.

3. Commit your changes.

- In the *Commit changes* section, describe your changes.
- Select the **Create a new branch for this commit and start a pull request** option
- Click **Propose changes**.
- Describe the changes you have made
- Select the **Create a new branch for this commit** and name your branch
- Click **Propose changes** to create the pull request

4. GitHub creates a branch and a commit for your changes. It loads a new page on which you can open a pull request to Percona. The page shows the base branch - the one you offer your changes for, your commit message and a diff - a visual representation of your changes against the original page. This allows you to make a last-minute review. When you are ready, click the **Create pull request** button.
5. Someone from our team reviews the pull request and if everything is correct, merges it into the documentation. Then it gets published on the site.
4. GitHub creates a branch and a commit for your changes. It loads a new page on which you can open a pull request to Percona. The page shows the base branch - the one you offer your changes for, your commit message and a diff - a visual representation of your changes against the original page. This allows you to make last-minute changes. When you are ready, click the **Create pull request** button.

### Edit documentation locally
5. Your changes will be reviewed and merged into the documentation.

This option is for users who prefer to work from their computer and / or have the full control over the documentation process.
### Edit documentation locally

The steps are the following:
If you want to work on your computer locally, follow these steps:

1. Fork this repository
2. Clone the repository on your machine:

```sh
git clone git@github.com:percona/postgresql-docs.git
git clone git@github.com:<my_name>/postgresql-docs.git
cd postgresql-docs
```

3. Change the directory to ``postgresql-docs`` and add your local repository:
3. Add the upstream (Percona) repository as a remote:

```sh
git remote add <your-repo-name> git@github.com:<your_name>/postgresql-docs.git
git remote add upstream git@github.com:percona/postgresql-docs.git
```

4. Pull the latest changes
4. Pull the latest changes

```sh
git fetch origin
git merge origin/<branch>
git fetch upstream
git merge upstream/<branch>
```

Make sure that your local branch and the branch you merge changes from are the same. So if you are on ``14`` branch, merge changes from ``origin/14``.
Make sure you merge changes from the same documentation branch you are working on. For example, if you are on branch ``14``, merge from ``upstream/14``.

5. Create a separate branch for your changes
5. Create a separate branch for your changes. If you work on a Jira issue, please follow this pattern for a branch name: `<PG-123>-short-description`:

```sh
git checkout -b <my_changes>
git checkout -b <PG-123>-short-description upstream/<target-branch>
```

6. Make changes
7. Commit your changes
8. Open a pull request to Percona

### Building the documentation

To verify how your changes look, generate the static site with the documentation. This process is called *building*. You can do it in these ways:

- [use Docker](#use-docker)
- [install MkDocs and build locally](#install-mkdocs-and-build-locally)

Learn more about the documentation structure in the [Repository structure](#repository-stucture) section.


#### Use Docker

1. [Get Docker :octicons-link-external-16: :octicons-link-external-16:](httpss://docs.docker.com/get-docker/)
2. We use [this Docker image :octicons-link-external-16: :octicons-link-external-16:](httpss://github.com/Percona-Lab/percona-doc-docker) to build documentation. Run the following command:
6. Make a commit mentioning the Jira issue in the commit message if any:

```sh
docker run --rm -v $(pwd):/docs perconalab/pmm-doc-md mkdocs build
git add .
git commit -m "PG-123-<my_fixes>"
git push -u origin <my_branch_name>
```

If Docker can't find the image locally, it first downloads the image, and then runs it to build the documentation.
7. Open a pull request to Percona

3. Go to the ``site`` directory and open the ``index.html`` file to see the documentation.
4. To view your changes as you make them, run the following command:
### Building the documentation using MkDocs

``` sh
docker run --rm -p 8000:8000 -v $(pwd):/docs perconalab/pmm-doc-md mkdocs serve -a 0.0.0.0:8000
```
To verify how your changes look, generate the static site with the documentation. This process is called *building*.

5. To create a PDF version of the documentation, run the following command:
> **NOTE**
> Learn more about the documentation structure in the [Repository structure](#repository-structure) section.

```sh
docker run --rm -v $(pwd):/docs perconalab/pmm-doc-md mkdocs build -f mkdocs-pdf.yml
```
To verify how your changes look, you can generate a static site locally:

The PDF document is in the ``site/pdf`` folder.
1. Install [pip](https://pip.pypa.io/en/stable/installing/)
2. Install [MkDocs](https://www.mkdocs.org/getting-started/#installation).
3. Install all the required dependencies:

#### Install MkDocs and build locally
```sh
pip install -r requirements.txt
```

1. Install [pip :octicons-link-external-16: :octicons-link-external-16:](httpss://pip.pypa.io/en/stable/installing/)
2. Install [MkDocs :octicons-link-external-16: :octicons-link-external-16:](httpss://www.mkdocs.org/getting-started/#installation).
3. While in the root directory of the doc project, run the following command to build the documentation:
4. While in the root directory of the documentation project, run the following command to build the documentation:

```sh
mkdocs build
```
4. Go to the ``site`` directory and open the ``index.html`` file in your web browser to see the documentation.
5. To automatically rebuild the documentation and reload the browser as you make changes, run the following command:

5. Go to the ``site`` directory and open the ``index.html`` file in your web browser to see the documentation.
6. To automatically rebuild the documentation and reload the browser as you make changes, run the following command:

```sh
mkdocs serve
```

6. To build the PDF documentation, do the following:
7. To build the PDF documentation, do the following:
- Install [mkdocs-print-site-plugin](https://timvink.github.io/mkdocs-print-site-plugin/index.html)
- Run the following command

```sh
mkdocs build
mkdocs build
```

This creates a single HTML page for the whole doc project. You can find the page at `site/print_page.html`.

7. Open the `site/print_page.html` in your browser and save as PDF. Depending on the browser, you may need to select the Export to PDF, Print - Save as PDF or just Save and select PDF as the output format.
This creates a single HTML page for the whole doc project. You can find the page at `site/print_page.html`.

8. Open the `site/print_page.html` in your browser and save as PDF. Depending on the browser, you may need to select the Export to PDF, Print - Save as PDF or just Save and select PDF as the output format.

You can also view the site at <http://127.0.0.1:8000>.

## Repository structure

The repository includes the following directories and files:

- `mkdocs-base.yml` - the base configuration file. It includes general settings and documentation structure.
- `mkdocs.yml` - configuration file. Contains the settings for building the docs on Percona website
- `mkdocs.yml` - configuration file. Contains the settings for building the documentation on Percona website
- `docs`:
- `*.md` - Source markdown files.
- `_images` - Images, logos and favicons
- `css` - Styles
- `js` - Javascript files
- `templates` - the PDF cover page template
- `_resource`:
- `overrides` - The directory with customized templates for HTML output
- `main.html` - The layout template for hosting the documentation on Percona website
- `templates`:
- `pdf_cover_page.tpl` - The PDF cover page template
- `_resourcepdf`:
- `overrides` - The directory with customized layout templates for PDF
- `.github`:
- `workflows`:
- `main.yml` - The workflow configuration for building documentation with a GitHub action. (The documentation is built with `mike` tool to a dedicated `publish` branch)
- `site` - This is where the output HTML files are put after the build
- `snippets` - The folder with pieces of documentation used in multiple places
- `snippets` - The folder with pieces of documentation used in multiple places
- `site` - This is where the output HTML files are put after the build