-
-
Notifications
You must be signed in to change notification settings - Fork 17
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Updated docs and fixed command kwargs
- Loading branch information
1 parent
c6f74e5
commit 500ccbc
Showing
6 changed files
with
98 additions
and
35 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 |
---|---|---|
@@ -1,3 +1,7 @@ | ||
[flake8] | ||
max-line-length = 100 | ||
max-line-length = 88 | ||
exclude = build/* | ||
extend-ignore = | ||
# See https://github.com/PyCQA/pycodestyle/issues/373 | ||
E203, | ||
ignore = E402, W503 |
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
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 |
---|---|---|
@@ -1,13 +1,11 @@ | ||
--- | ||
|
||
name: PyArr CI | ||
name: CI | ||
|
||
on: | ||
push: | ||
tags: | ||
- 'v*' | ||
branches: | ||
- master | ||
pull_request: | ||
branches: | ||
- master | ||
|
@@ -22,9 +20,16 @@ jobs: | |
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | ||
steps: | ||
- uses: actions/checkout@v2 | ||
# Use this GitHub Action | ||
- name: Check if Python files changed | ||
id: changed-files | ||
uses: tj-actions/changed-files@v9 | ||
with: | ||
files: | | ||
.py | ||
pyproject.toml | ||
- name: Check package version | ||
uses: marksie1988/tag_check@patch-1 | ||
if: steps.changed-files-specific.outputs.any_changed == 'true' | ||
uses: dudo/[email protected] | ||
with: | ||
git_tag_prefix: v | ||
black: | ||
|
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
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
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 |
---|---|---|
@@ -1,46 +1,89 @@ | ||
************ | ||
############ | ||
Contributing | ||
************ | ||
|
||
Modifying the module | ||
==================== | ||
############ | ||
|
||
It is recommended that contributions to this project are created within vscode, | ||
utilising the devcontainer functionality. | ||
|
||
This ensures that all developers are using the same environment and reduces the | ||
risk of adding bugs / issues within the project. | ||
This ensures that all developers are using the same environment and extentions. | ||
This reduces the risk of additional bugs / formatting issues within the project. | ||
|
||
.. note:: | ||
The setup of VSCode devcontainer is outside of the scope of this document | ||
additional information can be found within the VSCode documentation. | ||
|
||
Making changes | ||
-------------- | ||
********************** | ||
Setup your environment | ||
********************** | ||
|
||
#. Fork the `repository <https://github.com/totaldebug/pyarr>`_ | ||
#. Open the repository in VSCode | ||
#. Copy the .devcontainer/recommended-*** files and remove the "recommended-" text | ||
#. Press ``ctrl + shift + p`` and select ``Remote-Container: Reopen in Container`` | ||
#. Once loaded you can begin modification of the module or Documentation | ||
********************* | ||
Updating PyArr module | ||
********************* | ||
|
||
Style & formatting | ||
================== | ||
|
||
- Must follow PEP8 / Black formatting. (devcontainer is setup to reformat on save) | ||
- All functions must use google docstring format, the devcontainer has an | ||
`autodocstring <https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring>`_ | ||
plugin which will auto fill. | ||
- ``pyproject.toml`` must be updated with a new version, the new versions should | ||
follow `semver <http://semver.org/>`_. | ||
- Each feature / bugfix etc. should have its own pull request. | ||
|
||
********************** | ||
Updating Documentation | ||
********************** | ||
|
||
#. Fork the repository | ||
#. Must follow PEP8 and Black formatting. | ||
#. pyproject.toml must be updated with a new version, the new versions should | ||
follow `semver <http://semver.org/>`. | ||
#. Re-generate API rst with sphinx | ||
..code:: Python | ||
The documentation for this project utilises `sphinx <https://www.sphinx-doc.org/>`_. | ||
Sphinx allows for automatic documenting of all classes / functions via DocString. | ||
|
||
sphinx-apidoc -o ./sphinx-docs ./pyarr | ||
To Update static pages, you can amend the ``.rst`` files in the ``sphinx-docs`` folder. | ||
|
||
#. Each change should have its own PR. | ||
#. All information should be filled out in the PR Template. | ||
#. Any PR that consists of multiple changes may be rejected. | ||
#. PRs must state if they are breaking changes and what would break by implementing. | ||
All Python Class / Function documentation is updated automatically by Github Actions and | ||
does not require any manual changes to be made. | ||
|
||
Sphinx documentation uses `reStructuredText <https://docutils.sourceforge.io/rst.html>`_ to format each of the pages. | ||
|
||
Releasing the module | ||
==================== | ||
*********************** | ||
Pull Requests & Release | ||
*********************** | ||
|
||
To release a new version of the module, core team will take the following steps: | ||
Now that you have made the changes required for your enhancement, a pull request | ||
is required for the core team to review the changes, request amendements or approve | ||
the work that you have completed. | ||
|
||
Pull Requests | ||
============= | ||
|
||
- Each feature / bugfix should have its own PR. This makes code review more efficient | ||
and allows for a clean changelog generation | ||
- If a Pull Request contains multiple changes, our core team may reject it | ||
- All information in the Pull Request template should be completed, when people look | ||
at what was done with this Pull Request it should be easy to tell from this template | ||
- It must state if the change is a Breaking Change, and what would break by implementing | ||
|
||
Release Changes | ||
================= | ||
|
||
To release a new version of the module or documentation updates, the core team | ||
will take the following steps: | ||
|
||
#. Reviewing and testing the PR that has been submitted to ensure all | ||
requirements have been met. | ||
#. Tag the release in git: ``git tag $NEW_VERSION``. | ||
#. Push the tag to GitHub: ``git push --tags origin``. | ||
#. If all tests complete the package will be automatically released to PyPI | ||
#. Github Action will re-create the documentation with Sphinx | ||
|
||
If the only change is to documentation, the workflow ``Sphinx Documentation Update`` | ||
will be run to update the documentation. | ||
|
||
Documentation updates don't require the version to be updated in ``pyproject.toml`` | ||
and also don't require tagging. |