From 61efd16d3c52c64ff1c6cba9f145c3610bfa4ee6 Mon Sep 17 00:00:00 2001 From: kieran-mackle Date: Sat, 16 Dec 2023 17:30:10 +1000 Subject: [PATCH] docs: updated contribution guidelines --- README.md | 102 +++--------------------------- docs/source/getting-started.md | 2 +- docs/source/other/contributing.md | 86 ++++++++++++++++++++++++- 3 files changed, 94 insertions(+), 96 deletions(-) diff --git a/README.md b/README.md index 2c892e7..3202cea 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,6 @@ defined by hyperpatches. Check out the
  • Usage
    • -
  • Contributing
    • @@ -61,16 +60,22 @@ python3 -m pip install -e ./ cd ../../../ ``` +#### PyMesh + +Having [PyMesh](https://github.com/PyMesh/PyMesh) installed can greatly enhance the capabilities +offered by `HyperVehicle`. However, it can be difficult to install. Troubleshooting +guide coming soon. + + ### Installation -First clone the repository, then install via pip as an editable install. +To install `hypervehicle` from source, use the command below. ``` -git clone https://github.com/kieran-mackle/hypervehicle -cd hypervehicle -python3 -m pip install -e ./ +pip install git+https://github.com/kieran-mackle/hypervehicle ``` +

    [back to top]

    @@ -79,90 +84,3 @@ Please see the [example geometry generation](docs/source/examples/x43.md) to generate a mockup of the X-43A, shown above.

    [back to top]

    - - - -## Contributing - - - -To contribute to `hypervehicle`, please read the instructions below -to maintain the styling of the code. - -### Setting up for Development - -1. Create a new Python virtual environment to isolate the package. You -can do so using [`venv`](https://docs.python.org/3/library/venv.html) or -[anaconda](https://www.anaconda.com/). - -2. Install the code in editable mode using the command below (run from -inside the `hypervehicle` root directory). - -``` -pip install -e .[all] -``` - -3. Install the [pre-commit](https://pre-commit.com/) hooks. - -``` -pre-commit install -``` - -4. Start developing! After following the steps above, you are ready -to start developing the code. Make sure to follow the guidelines -below. - - -### Developing *hypervehicle* - -- Before making any changes, create a new branch to develop on using -`git checkout -b new-branch-name`. - -- Run [black](https://black.readthedocs.io/en/stable/index.html) on any -code you modify. This formats it according to -[PEP8](https://peps.python.org/pep-0008/) standards. - -- Document as you go: use -[numpy style](https://numpydoc.readthedocs.io/en/latest/format.html) -docstrings, and add to the docs where relevant. - -- Write unit tests for the code you add, and include them in `tests/`. -This project uses [pytest](https://docs.pytest.org/en/7.2.x/). - -- Commit code regularly to avoid large commits with many changes. - -- Write meaningful commit messages, following the -[Conventional Commits standard](https://www.conventionalcommits.org/en/v1.0.0/). -The python package [commitizen](https://commitizen-tools.github.io/commitizen/) -is a great tool to help with this, and is already configured for this -repo. Simply stage changed code, then use the `cz c` command to make a -commit. - -- Open a [Pull Request](https://github.com/kieran-mackle/hypervehicle/pulls) -when your code is complete and ready to be merged. - - -### Building the Docs -To build the documentation, run the commands below. - -``` -cd docs/ -make html -xdg-open build/html/index.html -``` - -If you are actively developing the docs, consider using -[sphinx-autobuild](https://pypi.org/project/sphinx-autobuild/). -This will continuosly update the docs for you to see any changes -live, rather than re-building repeatadly. From the `docs/` -directory, run the following command: - -``` -sphinx-autobuild source/ build/html --open-browser -``` - - - -

    [back to top]

    - - diff --git a/docs/source/getting-started.md b/docs/source/getting-started.md index bb2f4a3..032e739 100644 --- a/docs/source/getting-started.md +++ b/docs/source/getting-started.md @@ -42,7 +42,7 @@ pip install hypervehicle ``` ### Installation from source -First clone the repository, then install via pip. +To install `hypervehicle` from source, use the command below. ``` pip install git+https://github.com/kieran-mackle/hypervehicle diff --git a/docs/source/other/contributing.md b/docs/source/other/contributing.md index c4ea3fb..982ede2 100644 --- a/docs/source/other/contributing.md +++ b/docs/source/other/contributing.md @@ -1,6 +1,86 @@ # Contribution Guidelines -```{include} ../../../README.md -:start-after: -:end-before: +To contribute to `HyperVehicle`, please read the instructions below +to maintain the styling of the code. + + +## Seek Feedback Early +Please open an [issue](https://github.com/kieran-mackle/hypervehicle/issues) before a +[pull request](https://github.com/kieran-mackle/hypervehicle/pulls) to discuss any +changes you wish to make. + + +## Setting up for Development + +1. Create a new Python virtual environment to isolate the package. You +can do so using [`venv`](https://docs.python.org/3/library/venv.html) or +[anaconda](https://www.anaconda.com/). + +2. Install the code in editable mode using the command below (run from +inside the `hypervehicle` root directory). + +``` +pip install -e .[all] +``` + +3. Install the [pre-commit](https://pre-commit.com/) hooks. This will check +that your changes are formatted correctly before you make any commits. + +``` +pre-commit install +``` + +4. Start developing! After following the steps above, you are ready +to start developing the code. Make sure to follow the guidelines +below. + + +## Developing *HyperVehicle* + +- Before making any changes, fork this repository and clone it to your machine. + +- Run [black](https://black.readthedocs.io/en/stable/index.html) on any +code you modify. This formats it according to +[PEP8](https://peps.python.org/pep-0008/) standards. + +- Document as you go: use +[numpy style](https://numpydoc.readthedocs.io/en/latest/format.html) +docstrings, and add to the docs where relevant. + +- Write unit tests for the code you add, and include them in `tests/`. +This project uses [pytest](https://docs.pytest.org/en/7.2.x/). + +- Commit code regularly to avoid large commits with many unrelated changes. + +- Write meaningful commit messages, following the +[Conventional Commits standard](https://www.conventionalcommits.org/en/v1.0.0/). +This is used for the purpose of maintaining semantic versioning and automated +[changelogs](../changelog). +The Python package [`commitizen`](https://commitizen-tools.github.io/commitizen/) +is a great tool to help with this, and is already configured for this +repo. Simply stage changed code, then use the `cz c` command to make a +commit. If you do not wish to do this, your commits will be squashed before being +merged into `main`. + +- Open a [Pull Request](https://github.com/kieran-mackle/hypervehicle/pulls) +when your code is complete and ready to be merged. + + +## Building the Docs +To build the documentation, run the commands below. + +``` +cd docs/ +make html +xdg-open build/html/index.html +``` + +If you are actively developing the docs, consider using +[sphinx-autobuild](https://pypi.org/project/sphinx-autobuild/). +This will continuosly update the docs for you to see any changes +live, rather than re-building repeatadly. From the root +directory, run the following command: + +``` +sphinx-autobuild docs/source/ docs/build/html --open-browser ```