diff --git a/.gitignore b/.gitignore index aa769a1c..e2339635 100644 --- a/.gitignore +++ b/.gitignore @@ -224,3 +224,5 @@ Cargo.lock # These are backup files generated by rustfmt **/*.rs.bk + +.DS_Store diff --git a/pywr-book/src/SUMMARY.md b/pywr-book/src/SUMMARY.md index d4fbe8be..3ba6792b 100644 --- a/pywr-book/src/SUMMARY.md +++ b/pywr-book/src/SUMMARY.md @@ -18,3 +18,4 @@ - [Version control](./model-management/version-control.md) - [Packaging](./model-management/packaging.md) - [Deployment & Docker](./model-management/deployment.md) +- [Documentation](./building_documentation.md) diff --git a/pywr-book/src/building_documentation.md b/pywr-book/src/building_documentation.md new file mode 100644 index 00000000..7a6c9c36 --- /dev/null +++ b/pywr-book/src/building_documentation.md @@ -0,0 +1,64 @@ +# Contributing to Documentation + +The documentation for Pywr V2 is located in the pywr-next repository, [here](https://github.com/pywr/pywr-next) in the `pywr-book` subfolder. + +The documentation is written using 'markdown', a format which enables easy formatting for the web. + +This website can help get started: [www.markdownguide.org](https://www.markdownguide.org) + +To contribute documentation for Pywr V2, we recommend following the steps below to ensure we can review and integrate any changes as easily as possible. + +## Steps to create documentation + +1. Fork the pywr-next repository + +![Fork the repository](./images/making_documentation/fork.png "Fork") + +2. Clone the fork + +``` + git clone https://github.com/MYUSER/pywr-next +``` + +3. Create a branch + +``` + git checkout -b my-awesome-docs +``` + +4. Open the book documentation in your favourite editor + +``` + vi pywr-next/pywr-book/introduction.md +``` + +Which should look something like this: + +![An example docs file](./images/making_documentation/docs_example.png "Docs example") + +5. Having modified the documentation, add and commit the changes using the commit format + +``` +git add introduction.md" +``` + +``` +git commit -m "docs: Add an example documentation" +``` + +6. Create a pull request from your branch + 1. In your fork, click on the 'Pull Requests' tab + ![Pull request](./images/making_documentation/pr1.png "Pull Request") + + 2. Click on 'New Pull Request' + ![Pull request](./images/making_documentation/pr2.png "Pull Request") + + 3. Choose your branch from the drop-down on the right-hand-side + ![Pull request](./images/making_documentation/pr3.png "Pull Request") + + 4. Click 'Create Pull Request' when the button appears + ![Pull request](./images/making_documentation/pr4.png "Pull Request") + + 5. Add a note if you want, and click 'Create Pull Request' + ![Pull request](./images/making_documentation/pr5.png "Pull Request") + diff --git a/pywr-book/src/images/making_documentation/docs_example.png b/pywr-book/src/images/making_documentation/docs_example.png new file mode 100644 index 00000000..9c08470c Binary files /dev/null and b/pywr-book/src/images/making_documentation/docs_example.png differ diff --git a/pywr-book/src/images/making_documentation/fork.png b/pywr-book/src/images/making_documentation/fork.png new file mode 100644 index 00000000..4593dab9 Binary files /dev/null and b/pywr-book/src/images/making_documentation/fork.png differ diff --git a/pywr-book/src/images/making_documentation/pr1.png b/pywr-book/src/images/making_documentation/pr1.png new file mode 100644 index 00000000..cd028f90 Binary files /dev/null and b/pywr-book/src/images/making_documentation/pr1.png differ diff --git a/pywr-book/src/images/making_documentation/pr2.png b/pywr-book/src/images/making_documentation/pr2.png new file mode 100644 index 00000000..4d4b6b90 Binary files /dev/null and b/pywr-book/src/images/making_documentation/pr2.png differ diff --git a/pywr-book/src/images/making_documentation/pr3.png b/pywr-book/src/images/making_documentation/pr3.png new file mode 100644 index 00000000..7e177bcd Binary files /dev/null and b/pywr-book/src/images/making_documentation/pr3.png differ diff --git a/pywr-book/src/images/making_documentation/pr4.png b/pywr-book/src/images/making_documentation/pr4.png new file mode 100644 index 00000000..ade214ef Binary files /dev/null and b/pywr-book/src/images/making_documentation/pr4.png differ diff --git a/pywr-book/src/images/making_documentation/pr5.png b/pywr-book/src/images/making_documentation/pr5.png new file mode 100644 index 00000000..c93e3c91 Binary files /dev/null and b/pywr-book/src/images/making_documentation/pr5.png differ diff --git a/pywr-book/src/introduction.md b/pywr-book/src/introduction.md index 2e6a8d7e..306fcd4d 100644 --- a/pywr-book/src/introduction.md +++ b/pywr-book/src/introduction.md @@ -12,4 +12,4 @@ It allows users to construct models of water systems using a network of nodes an The model can then be used to simulate the operation of a water system, and to evaluate the performance of the system under different scenarios. This version is a major update to the original Pywr model, which was written in Python and Cython. -The new version is written in Rust, and uses Python bindings to expose the functionality to Python. +The new version is written in Rust, and uses Python bindings to expose the functionality to Python. \ No newline at end of file