You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[Comment on pull requests](#comment-on-pull-requests)
16
+
-[Review pull requests](#review-pull-requests)
17
+
-[Build locally](#build-locally)
18
+
-[Prerequisites](#prerequisites)
19
+
-[Setup](#setup)
20
+
-[Build commands](#build-commands)
21
+
-[Troubleshooting](#troubleshooting)
17
22
18
23
## Contribute to Mattermost product documentation
19
24
@@ -56,78 +61,63 @@ If you've downloaded the `mattermost/docs` repository to edit Mattermost documen
56
61
> [!NOTE]
57
62
> You can generate the docs on Linux, Mac, and Windows (using PowerShell); however, builds on Windows are considerably slower because only a single processing core is used.
58
63
>
59
-
> For faster local docs builds on Windows, we strongly recommend [installing WSL](https://learn.microsoft.com/en-us/windows/wsl/install) to create an Ubuntu virtual machine (VM), where you'll configure the following prerequisites. An Ubuntu VM will use all available processing cores, resulting in faster local builds.
64
+
> For faster local docs builds on Windows, we strongly recommend [installing WSL](https://learn.microsoft.com/en-us/windows/wsl/install) to create an Ubuntu virtual machine (VM), where you'll configure the following prerequisites. This VM will be using all available processing cores, resulting in faster local builds.
60
65
61
-
### Build prerequisites
62
-
63
-
The following software is required to build the documentation:
66
+
### Prerequisites
64
67
65
68
- Git [[download]](https://git-scm.com/downloads)
66
69
- Python 3.11 or later [[download]](https://www.python.org/downloads)
67
70
- Pipenv [[download]](https://pipenv.pypa.io)
68
71
- GNU Make 3.82 or later
69
72
70
-
### Build instructions
73
+
> [!NOTE]
74
+
> Windows users who aren't using WSL require `make` installed. To install via Chocolatey: run `choco install make` in an admin PowerShell terminal after installing [chocolatey](https://chocolatey.org/).
75
+
76
+
### Setup
71
77
72
-
1. Open a native or VM terminal window, then clone a forked copy of the documentation repository:
73
-
```shell
74
-
git clone https://github.com/mattermost/docs.git
75
-
```
78
+
1. Clone the repository and navigate to it:
79
+
```shell
80
+
git clone https://github.com/mattermost/docs.git
81
+
cd docs
82
+
```
76
83
77
-
2. In the terminal window, navigate into the cloned repository:
78
-
```shell
79
-
cd docs
80
-
```
84
+
2.Install pipenv:
85
+
```shell
86
+
# Using Homebrew
87
+
brew install pipenv
81
88
82
-
3. Install [pipenv](https://docs.pipenv.org/) by using one of the following commands based on your operating system:
89
+
# Using pip
90
+
pip install --user pipenv
91
+
```
83
92
84
-
For Mac users and Ubuntu VM users where Homebrew is installed:
85
-
```shell
86
-
brew install pipenv
87
-
```
93
+
3. Install dependencies (choose one):
94
+
```shell
95
+
# For local development (recommended for first-time setup)
96
+
pipenv install --dev
88
97
89
-
For other operating systems:
90
-
```shell
91
-
pip install --user pipenv
92
-
```
98
+
# For exact reproducibility (CI/CD or team environments)
99
+
pipenv sync --dev
100
+
```
93
101
94
-
4. Install required Python packages. You have two options:
102
+
4. Initialize Git submodules:
103
+
```shell
104
+
git submodule update --init --recursive
105
+
```
95
106
96
-
Use `pipenv sync --dev` when:
97
-
- You need exact reproducibility of the production build environment.
98
-
- You're setting up a CI/CD pipeline.
99
-
- You want to avoid accidentally updating dependency versions.
100
-
- You're working in a team where everyone should use identical package versions.
107
+
### Build commands
101
108
102
-
Use `pipenv install --dev` when:
103
-
- You're setting up a local development environment for the first time.
104
-
- You want to allow minor package updates within the version constraints.
105
-
- You're working independently from production and want the most recent compatible versions.
109
+
-**`gmake html`** - Build only modified files (fastest for iterative changes)
110
+
-**`gmake clean html`** - Clean build directory and rebuild all files
111
+
-**`gmake livehtml`** - Start live preview server at `http://127.0.0.1:8000` (auto-updates on save)
106
112
107
-
5. Run ``git submodule update --init --recursive`` to ensure that the Git submodules for Mattermost Agents are initialized and updated.
113
+
Static build output is located in `build/html/index.html`. Build errors are logged to `build/warnings.log` and redirect issues are logged to `build/redirect-warnings.log`.
108
114
109
-
6. Build the documentation set. You have three build commands available at the terminal:
115
+
### Troubleshooting
110
116
111
-
- Use `gmake html` to generate HTML files in the `/build` directory. Only file you've modified are re-built.
112
-
- Use `gmake clean html` to delete all static HTML output in the `/build` directory and re-build all files. This command is particularly useful when you're making changes to the left navigation pane and want to ensure you're not reviewing cached results.
113
-
- Use `gmake livehtml` to review a live preview published to `http://127.0.0.1:8000` that automatically updates as new changes are saved in your local IDE. Always run `gmake clean html` first before reviewing a live preview.
117
+
**What if my local build starts becoming slow?**
114
118
115
-
> [!NOTE]
116
-
> Windows users who aren't building the docs in an Ubuntu VM also require `make` installed for the build commands above to work correctly. To install `make` via Chocolatey:
> 2. In a Windows terminal, selectthe downward chevron, and hold `CTRL`while selecting **PowerShell** to run commands as an admin.
120
-
> 3. Accept the admin prompt.
121
-
> 4. Run the following command: `choco install make`
122
-
> 5. Exit the terminal.
123
-
>
124
-
> When building the Mattermost Product Documentation locally, Windows users will see slower build speeds because only a single processing core is used to build the docs. Mac & Linux users will see faster build speeds because multiple cores are used to build. This is a limitation of Sphinx on Windows platforms.
125
-
126
-
7. When working with static build results, navigate to the `build` directory:
127
-
```sh
128
-
cd build
129
-
```
130
-
131
-
8. Then, preview your changes by opening the `build/html/index.html` file.
132
-
133
-
Build errors are written to the `build/warnings.log` file. Errors regarding redirects are written to the `build/redirect-warnings.log` file.
119
+
Run `make clean` and rebuild the repository from scratch:
0 commit comments