-
Notifications
You must be signed in to change notification settings - Fork 7
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.
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
Add a Contributing guide #15
Open
settermjd
wants to merge
3
commits into
laminas:master
Choose a base branch
from
settermjd:add-contributing-guide
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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,78 @@ | ||
# 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. Install [the PyMdown Extensions]. | ||
3. Clone the [documentation-theme repository] locally. | ||
``` | ||
git clone [email protected]:laminas/documentation-theme.git documentation-theme | ||
``` | ||
4. Symlink the theme directory from the cloned documentation-theme repository, to the root directory of this project. | ||
5. Add the symlinked directory to .gitignore, to exclude it from being versioned with the project. | ||
6. Add the following Yaml snippet to `mkdocs.yml`, changing it 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/<your-project>' | ||
extra: | ||
repo_name: <your-project> | ||
# 'Mezzio' and 'MVC' can also be used as the project value | ||
project: Components | ||
settermjd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
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: | ||
froschdesign marked this conversation as resolved.
Show resolved
Hide resolved
|
||
- 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 | ||
``` | ||
|
||
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 | ||
[the PyMdown Extensions]: https://facelessuser.github.io/pymdown-extensions/installation/ | ||
froschdesign marked this conversation as resolved.
Show resolved
Hide resolved
|
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.