From c426ae326637f5b13f826bbcb0cc88684f97386b Mon Sep 17 00:00:00 2001 From: Mathieu Kniewallner Date: Tue, 3 Jan 2023 20:33:13 +0100 Subject: [PATCH] docs: move `Contributing` to `docs` (#259) --- CONTRIBUTING.rst | 143 ------------------------------------------- README.md | 18 +++--- docs/contributing.md | 109 +++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 4 files changed, 118 insertions(+), 153 deletions(-) delete mode 100644 CONTRIBUTING.rst create mode 100644 docs/contributing.md diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index f3a5612a..00000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,143 +0,0 @@ -============ -Contributing -============ - -Contributions are welcome, and they are greatly appreciated! Every little bit -helps, and credit will always be given. - -You can contribute in many ways: - -Types of Contributions ----------------------- - -Report Bugs -~~~~~~~~~~~ - -Report bugs at https://github.com/fpgmaas/deptry/issues - -If you are reporting a bug, please include: - -* Your operating system name and version. -* Any details about your local setup that might be helpful in troubleshooting. -* Detailed steps to reproduce the bug. - -Fix Bugs -~~~~~~~~ - -Look through the GitHub issues for bugs. Anything tagged with "bug" -and "help wanted" is open to whoever wants to implement a fix for it. - -Implement Features -~~~~~~~~~~~~~~~~~~ - -Look through the GitHub issues for features. Anything tagged with "enhancement" -and "help wanted" is open to whoever wants to implement it. - -Write Documentation -~~~~~~~~~~~~~~~~~~~ - -Cookiecutter PyPackage could always use more documentation, whether as part of -the official docs, in docstrings, or even on the web in blog posts, articles, -and such. - -Submit Feedback -~~~~~~~~~~~~~~~ - -The best way to send feedback is to file an issue at -https://github.com/fpgmaas/deptry/issues. - -If you are proposing a new feature: - -* Explain in detail how it would work. -* Keep the scope as narrow as possible, to make it easier to implement. -* Remember that this is a volunteer-driven project, and that contributions - are welcome :) - -Get Started! ------------- - -Ready to contribute? Here's how to set up `deptry` for local -development. Please note this documentation assumes you already have -`poetry` and `Git` installed and ready to go. - -| 1. Fork the `deptry` repo on GitHub. - -| 2. Clone your fork locally: - - .. code-block:: bash - - cd - git clone git@github.com:YOUR_NAME/deptry.git - - -| 3. Now we need to install the environment. Navigate into the directory - - .. code-block:: bash - - cd deptry - - If you are using ``pyenv``, select a version to use locally. (See installed versions with ``pyenv versions``) - - .. code-block:: bash - - pyenv local - - Then, install the virtual environment with: - - .. code-block:: bash - - poetry install - -| 4. Install pre-commit to run linters/formatters at commit time: - - .. code-block:: bash - - poetry run pre-commit install - -| 5. Create a branch for local development: - - .. code-block:: bash - - git checkout -b name-of-your-bugfix-or-feature - - Now you can make your changes locally. - -| 6. Don't forget to add test cases for your added functionality to the ``tests`` directory. - -| 7. Once you're done, validate that all unit tests are passing: - - .. code-block:: bash - - make test - -| 8. Before creating a pull request you should also run tox. This will run the - tests across different versions of Python: - - .. code-block:: bash - - tox - - This requires you to have multiple versions of Python installed. - This step is also triggered in the CI/CD pipeline, so you could also choose to skip this - step locally. - -| 9. Commit your changes and push your branch to GitHub: - - .. code-block:: bash - - git add . - git commit -m "Your detailed description of your changes." - git push origin name-of-your-bugfix-or-feature - -| 10. Submit a pull request through the GitHub website. - -Pull Request Guidelines ---------------------------- - -Before you submit a pull request, check that it meets these guidelines: - -1. The pull request should include tests. - -2. If the pull request adds functionality, the docs should be updated. Put your - new functionality into a function with a docstring, and add the feature to - the list in README.rst. diff --git a/README.md b/README.md index 0fb54da6..2ea9b83f 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -

+

deptry logo

@@ -19,7 +19,7 @@ Dependency issues are detected by scanning for imported modules within all Pytho ---

- Link to documentation + Documentation - Contributing

--- @@ -34,15 +34,14 @@ _deptry_ can be added to your project with poetry add --group dev deptry ``` -or with +or with: -``` +```shell pip install deptry ``` -> **Warning** -> When using pip to install _deptry_, make sure you install it within the virtual environment of your project. Installing _deptry_ globally will not work, since it needs to have access to the metadata of the packages in the virtual environment. +> **Warning**: When using pip to install _deptry_, make sure you install it within the virtual environment of your project. Installing _deptry_ globally will not work, since it needs to have access to the metadata of the packages in the virtual environment. ### Prerequisites @@ -50,14 +49,13 @@ _deptry_ should be run within the root directory of the project to be scanned, a ### Usage -To scan your project for dependency issues, run +To scan your project for dependency issues, run: -```sh +```shell deptry . ``` -_deptry_ can be configured by using additional command line arguments, or -by adding a `[tool.deptry]` section in _pyproject.toml_. +_deptry_ can be configured by using additional command line arguments, or by adding a `[tool.deptry]` section in _pyproject.toml_. For more information, see the [documentation](https://fpgmaas.github.io/deptry/). diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 00000000..b892fa62 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,109 @@ +# Contributing + +Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. + +You can contribute in many ways. + +## Types of contributions + +### Reporting bugs + +Report bugs at https://github.com/fpgmaas/deptry/issues. + +If you are reporting a bug, please include: + +* Your operating system name and version. +* Any details about your local setup that might be helpful in troubleshooting. +* Detailed steps to reproduce the bug. + +### Fixing bugs + +Look through the GitHub issues for bugs. Anything tagged with `bug` and `help wanted` is open to whoever wants to implement a fix for it. + +### Implementing features + +Look through the GitHub issues for features. Anything tagged with `enhancement` and `help wanted` is open to whoever wants to implement it. + +### Writing documentation + +_deptry_ could always use more documentation, whether as part of the official documentation, in docstrings, or even on the web in blog posts, articles, and such. + +### Submitting feedback + +The best way to send feedback is to file an issue at https://github.com/fpgmaas/deptry/issues. + +If you are proposing a new feature: + +* Explain in detail how it would work. +* Keep the scope as narrow as possible, to make it easier to implement. +* Remember that this is a volunteer-driven project, and that contributions are welcome :) + +## Get started! + +Ready to contribute? Here's how to set up _deptry_ for local development. Please note this documentation assumes you already have [Poetry](https://python-poetry.org/) and [Git](https://git-scm.com/) installed and ready to go. + +1. [Fork](https://github.com/fpgmaas/deptry/fork) the _deptry_ repository on GitHub. + +2. Clone your fork locally: + ```bash + cd + git clone git@github.com:YOUR_NAME/deptry.git + ``` + +3. Now you need to set up your local environment. Navigate into the directory: + ```bash + cd deptry + ``` + + If you are using [pyenv](https://github.com/pyenv/pyenv), select a version to use locally (see installed versions with `pyenv versions`): + ```bash + pyenv local + ``` + + Then, install the virtual environment with: + ```bash + poetry install + ``` + +4. Install [pre-commit](https://pre-commit.com/) to run linters/formatters at commit time: + ```bash + poetry run pre-commit install + ``` + +5. Create a branch for local development: + ```bash + git checkout -b name-of-your-bugfix-or-feature + ``` + + Now you can make your changes locally. + +6. If you are adding a feature or fixing a bug, make sure to add tests in the `tests` directory. + +7. Once you're done, validate that all unit tests are passing: + ```bash + make test + ``` + +8. Before submitting a pull request, you should also run [tox](https://tox.wiki/en/latest/). This will run the tests across all the Python versions that _deptry_ supports: + ```bash + tox + ``` + + This requires you to have multiple versions of Python installed. + This step is also triggered in the CI pipeline, so you could also choose to skip this step locally. + +9. Commit your changes and push your branch to GitHub: + ```bash + git add . + git commit -m "Your detailed description of your changes." + git push origin name-of-your-bugfix-or-feature + ``` + +10. Submit a pull request through GitHub. + +## Pull request guidelines + +Before you submit a pull request, ensure that it meets the following guidelines: + +1. If the pull request adds a functionality or fixes a bug, the pull request should include tests. +2. If the pull request adds a functionality, the documentation in `docs` directory should probably be updated. diff --git a/mkdocs.yml b/mkdocs.yml index 8e5ff048..57cc2375 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,6 +11,7 @@ nav: - Home: index.md - Usage and Configuration: usage.md - Issues detection: issues-detection.md + - Contributing: contributing.md plugins: - search