-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
The intent of this PR is to move the changes in laminas/laminas-form#65 to a more globally accessible location, one that can be referenced in all of the sub-repositories of the Laminas and Mezzio organisations. Signed-off-by: Matthew Setter <[email protected]>
- Loading branch information
Showing
2 changed files
with
74 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,74 @@ | ||
# Contributing | ||
|
||
The documentation for each repository is available in the "**docs/**" directory of that repository. | ||
It is written in [Markdown format] and built using [MkDocs]. | ||
|
||
## Testing Your Changes Locally | ||
|
||
We **strongly** encourage you to test your changes locally before contributing them. | ||
To do so, you first need to do three things; these are: | ||
|
||
1. Have MkDocs installed. | ||
2. Have the Laminas documentation theme available to the laminas-form directory. | ||
3. Update `mkdocs.yml` to build the docs using the documentation theme. | ||
|
||
To complete these steps, please follow the instructions below. | ||
|
||
1. [Install MkDocs]. | ||
2. Clone the [documentation-theme repository] locally. | ||
``` | ||
git clone [email protected]:laminas/documentation-theme.git documentation-theme | ||
``` | ||
3. Copy the theme directory from the cloned documentation-theme repository to the root directory of this project. | ||
4. Replace lines 91 and 92 of `mkdocs.yml` with the following Yaml snippet, changing them to suit the repository that you are working with. | ||
```yaml | ||
# The following example assumes that you are working with laminas-form | ||
repo_url: 'https://github.com/laminas/laminas-form' | ||
extra: | ||
repo_name: laminas/laminas-form | ||
project: Components | ||
base_url: https://docs.laminas.dev/ | ||
project_url: https://docs.laminas.dev/components/ | ||
theme: | ||
name: null | ||
custom_dir: 'theme/' | ||
static_templates: | ||
- pages/404.html | ||
markdown_extensions: | ||
- pymdownx.superfences: | ||
- pymdownx.tabbed: | ||
- toc: | ||
toc_depth: 2 | ||
``` | ||
|
||
When you have completed each of these steps then, from the root directory of the project, run `mkdocs serve &`. | ||
This builds the documentation locally, making it available on `http://127.0.0.1:8000`, if the port is not already in use, and actively watch for changes. | ||
If changes are detected, the documentation is automatically regenerated, saving you the trouble of having to do so manually. | ||
|
||
You should see initial output similar to the following if the process is successful. | ||
|
||
```console | ||
INFO - Building documentation... | ||
INFO - Cleaning site directory | ||
INFO - Documentation built in 2.47 seconds | ||
[I 200430 22:06:08 server:296] Serving on http://127.0.0.1:8000 | ||
INFO - Serving on http://127.0.0.1:8000 | ||
[I 200430 22:06:08 handlers:62] Start watching changes | ||
INFO - Start watching changes | ||
[I 200430 22:06:08 handlers:64] Start detecting changes | ||
INFO - Start detecting changes | ||
``` | ||
|
||
Additionally, when you view the documentation, it should be properly themed, similar to the following screenshot. | ||
|
||
![Example of locally generated Laminas documentation](/images/example-of-generated-documentation.png) | ||
|
||
## Need Help? | ||
|
||
If you have trouble with any of these steps, come and ask for help in [the Laminas Slack #documentation channel]. | ||
|
||
[documentation-theme repository]: https://github.com/laminas/documentation-theme | ||
[Install MkDocs]: https://www.mkdocs.org/#installation | ||
[MkDocs]: https://www.mkdocs.org/ | ||
[Markdown format]: https://www.markdownguide.org/ | ||
[the Laminas Slack #documentation channel]: https://laminas.slack.com |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.