From 270a7e3a630dc602764e265e0f44da3b037af0af Mon Sep 17 00:00:00 2001 From: Marc Lebreuil Date: Sat, 4 May 2024 16:14:34 +0000 Subject: [PATCH] Add doc Changes to be committed: new file: .github/workflows/mkdocs.yaml modified: .github/workflows/python-publish.yml new file: CHANGELOG.md new file: CONTRIBUTING.md modified: README.md new file: docs/changelog.md new file: docs/contributing.md new file: docs/index.md new file: mkdocs.yml modified: pyproject.toml modified: src/netbox_contract/__init__.py --- .github/workflows/mkdocs.yaml | 17 ++++ .github/workflows/python-publish.yml | 1 + CHANGELOG.md | 91 ++++++++++++++++++++ CONTRIBUTING.md | 121 +++++++++++++++++++++++++++ README.md | 73 +--------------- docs/changelog.md | 3 + docs/contributing.md | 3 + docs/index.md | 3 + mkdocs.yml | 49 +++++++++++ pyproject.toml | 2 +- src/netbox_contract/__init__.py | 2 +- 11 files changed, 293 insertions(+), 72 deletions(-) create mode 100644 .github/workflows/mkdocs.yaml create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md create mode 100644 docs/changelog.md create mode 100644 docs/contributing.md create mode 100644 docs/index.md create mode 100644 mkdocs.yml diff --git a/.github/workflows/mkdocs.yaml b/.github/workflows/mkdocs.yaml new file mode 100644 index 0000000..910005e --- /dev/null +++ b/.github/workflows/mkdocs.yaml @@ -0,0 +1,17 @@ +name: ci +on: + push: + branches: + - main +permissions: + contents: write +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-python@v4 + with: + python-version: 3.x + - run: pip install mkdocs-material mkdocs-autorefs mkdocs-material-extensions mkdocstrings mkdocstrings-python-legacy mkdocs-include-markdown-plugin + - run: mkdocs gh-deploy --force \ No newline at end of file diff --git a/.github/workflows/python-publish.yml b/.github/workflows/python-publish.yml index bca511a..72d83ec 100644 --- a/.github/workflows/python-publish.yml +++ b/.github/workflows/python-publish.yml @@ -24,6 +24,7 @@ jobs: permissions: # IMPORTANT: this permission is mandatory for trusted publishing id-token: write + steps: - uses: actions/checkout@v4 - name: Set up Python diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..b16999c --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,91 @@ +# Changelog + +## [Unreleased] + +## Version 2.1 + +### Version 2.1.0 + +* Setup the documentation on Github pages +* Automate the creation of PiPY packages from releases with Github Actions +* Automate the creation of the release notes from CHANGELOG.md + +## Version 2 + +### Version 2.0.14 + +* [127](https://github.com/mlebreuil/netbox-contract/issues/127) Fix contract filtering +* Fix contact assignement. + +### Version 2.0.13 + +* [123](https://github.com/mlebreuil/netbox-contract/issues/123) prepare plugin to [Netbox 4.0 migration](https://docs.netbox.dev/en/feature/plugins/development/migration-v4/). +* [125](https://github.com/mlebreuil/netbox-contract/issues/125) Cleanup direct reference to Circuits in the Contract model. Correct database inconsistencies related to the ContractAssignment object renaming. + +### Version 2.0.11 + +* [115](https://github.com/mlebreuil/netbox-contract/issues/115) API correction for contract external partie +* [117](https://github.com/mlebreuil/netbox-contract/issues/117) Tenant and accounting dimensions optional +* [119](https://github.com/mlebreuil/netbox-contract/issues/119) Add a Yearly recuring cost, read only, calculated field for contract +* [15](https://github.com/mlebreuil/netbox-contract/issues/105) Quick serach limited to active contracts + +### Version 2.0.10 + +* [107](https://github.com/mlebreuil/netbox-contract/issues/107) Add the contacts tab to the service provider detail view. +* [111](https://github.com/mlebreuil/netbox-contract/issues/111) Correct assignment spelling. + +### Version 2.0.9 + +* [42](https://github.com/mlebreuil/netbox-contract/issues/42) Allow the selection of either providers or Service providers as contract third partie. +* Removed all reference to the direct assignement of circuits to contracts +* [88](https://github.com/mlebreuil/netbox-contract/issues/88) Add a placeholder value to the accounting dimensions jsonfield. This placeholder vale con be configured as part of the PLUGINS_CONFIG parameter in the configuration.py file (see above) +* [89](https://github.com/mlebreuil/netbox-contract/issues/89) add the posibility to link contracts to sites and virtual machines. +* [99](https://github.com/mlebreuil/netbox-contract/issues/99) list child contracts in on the parent view. + +### Version 2.0.8 + +* [#91](https://github.com/mlebreuil/netbox-contract/issues/91) Replace deprecated ( in netbox version 3.6) MultipleChoiceField. +* [48](https://github.com/mlebreuil/netbox-contract/issues/48) Allow other plugin to inject visual in contract and invoice forms. +* [89] (https://github.com/mlebreuil/netbox-contract/issues/89) Add contract assignement to virtual machines. + +### Version 2.0.7 + +* [#85](https://github.com/mlebreuil/netbox-contract/issues/85) Fix missing fields contract and invoice import and export forms. + +### Version 2.0.6 + +* [#80](https://github.com/mlebreuil/netbox-contract/issues/80) Fix missing fields in the API. + +### Version 2.0.5 + +* [#75](https://github.com/mlebreuil/netbox-contract/issues/74) Fix contract assignement for service providers. +* [#73](https://github.com/mlebreuil/netbox-contract/issues/73) Add comment field to contract import form +* [#72](https://github.com/mlebreuil/netbox-contract/issues/72) Add fields to the contract assignement bottom tables +* Remove the 'add' actions from the contract assignment list view + +### Version 2.0.4 + +* Add bulk update capability for contract assignement +* [#63](https://github.com/mlebreuil/netbox-contract/issues/63) Correct an API issue on the invoice object. +* [#64](https://github.com/mlebreuil/netbox-contract/issues/64) Add hierarchy to contract; New parent field created. +* [#65](https://github.com/mlebreuil/netbox-contract/issues/65) Add end date to contact import form. +* Removed the possibility of add or modify circuits to contracts. The field becomes read only and will be removed in next major release. +* Make accounting dimensions optional. + +### Version 2.0.3 + +* [#60](https://github.com/mlebreuil/netbox-contract/issues/60) Update contract quick search to also filter on fields "External reference" and "Comments". +* [#49](https://github.com/mlebreuil/netbox-contract/issues/49) Manage permissions. + +### Version 2.0.2 + +Add support for Netbox 3.5 which become the minimum version supported to accomodate the removal of NetBoxModelCSVForm class (replaced by NetBoxModelImportForm) . + +### Version 2.0.1 + +Add support contract assignement panel to devices. + +### Version 2.0.0 + +Add a new contract asignement model to allow the assignement of contract not only to Circuits. The support for the direct Contract to Circuit relation will be removed in version 2.1.0 . In Order to migrate existing relations contract_migration.py script is provided and can be run from the django shell. + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..abd9537 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,121 @@ +# Contributing + +Contributions are welcome! + +## Types of contributions + +### Report bugs or submit feedback + +Report bugs and submit feetback [here](https://github.com/mlebreuil/netbox-contract/issues). + +### Fix bugs + +Look through the GitHub issues for bugs. Anything tagged with "bug" and "help +wanted" is open to whoever wants to implement 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. + +## Coding conventions + +Netbox [Style Guide](https://docs.netbox.dev/en/stable/development/style-guide/) +Django [Coding style](https://docs.djangoproject.com/en/4.2/internals/contributing/writing-code/coding-style/) + +For this: +All files will be formated using the [black](https://black.readthedocs.io/en/stable/) auto-formatter. +Configuration is stored in pyproject.toml + +[isort](https://github.com/PyCQA/isort#readme) is used to automate import sorting. + +Linting and PEP8 style enforcement will be done with [Flake8](https://flake8.pycqa.org/en/latest/) which is a wrapper arround: +- PyFlakes +- pycodestyle +- Ned Batchelder’s McCabe script +Configuration is maintained in the .flake8 file (no support for pyproject.toml) + +The pre-commit Python framework is used to simplify the managment of pre-commit hooks. +Config is stored in .pre-commit-config.yaml + +## Repository structure + +There are 2 permanent branch in the repository: + +* master - The current stable release. Individual changes should never be pushed directly to this branch, but rather merged from develop. +* develop - Active development for the upcoming patch release. Pull requests will typically be based on this branch unless they introduce breaking changes that must be deferred until the next minor release. + +For each new feature or bug fix a branch is created from the corresponding issue. + +## Setup your development environment + +```bash +python -m pip install pre-commit +pre-commit install +``` +1. [Install Netbox](https://github.com/netbox-community/netbox/blob/develop/docs/installation/). +Make sure taht at the Netbox installtion step you follow the "Option B: Clone the Git Repository" + +2. From the Netbox directory you activate the NetBox virtual environment + + ``` + $ cd netbox + $ source venv/netbox/bin/activate + ``` + +3. Fork the [netbox-contract](https://github.com/mlebreuil/netbox-contract/) repo on GitHub. +4. Clone your fork locally + + ``` + $ cd .. + $ git clone git@github.com:your_name_here/netbox-contract.git + ``` + +5. Add the plugin to NetBox virtual environment: + + ``` + $ python3 -m pip install -e netbox-contract + ``` + +5. Update the Netbox configuration ans run the database migrations as mentionned in the plugin installation steps. +6. Create a branch for local development: + + ``` + $ git checkout -b name-of-your-bugfix-or-feature + ``` + + Make your changes locally. + +7. You can test your changes using the django development server: + + ``` + $ python3 netbox/netbox/manage.py runserver 0.0.0.0:8000 --insecure + ``` + + Connect to the name or IP of the server (as defined in ALLOWED_HOSTS) on port 8000; for example, http://127.0.0.1:8000/. + +7. Commit your changes and push your branch to GitHub: + + ``` + $ git add . + $ git commit -m "Your detailed description of your changes." + $ git push origin name-of-your-bugfix-or-feature + ``` + +7. 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. +3. The pull request should work for Python 3.8, 3.9, 3.10 and 3.11. Check [Actions](https://github.com/mlebreuil/netbox-contract/actions) + and make sure that the tests pass for all supported Python versions. + + +## Deploying + +A reminder for the maintainers on how to deploy. +Make sure all your changes are committed (including an entry in CHANGELOG.md) and that all tests pass. +Then in the github project go to `Releases` and create a new release with a new tag. This will automatically upload the release to pypi: diff --git a/README.md b/README.md index c3b2082..7018f6e 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,9 @@ ## Overview The pluggin adds contracts and invoices model to Netbox. It allows to register contract with objects. -Add invoices to contracts. +Add invoices to contracts. + +Check the [documentation](https://mlebreuil.github.io/netbox-contract/) for additional information ## Installation @@ -90,72 +92,3 @@ FIELD_CHOICES = { (venv) $ cd /opt/netbox/netbox/ (venv) $ python3 manage.py migrate ``` - -## release notes - -### version 2.0.0 - -Add a new contract asignement model to allow the assignement of contract not only to Circuits. The support for the direct Contract to Circuit relation will be removed in version 2.1.0 . In Order to migrate existing relations contract_migration.py script is provided and can be run from the django shell. - -#### version 2.0.1 - -Add support contract assignement panel to devices. - -#### version 2.0.2 - -Add support for Netbox 3.5 which become the minimum version supported to accomodate the removal of NetBoxModelCSVForm class (replaced by NetBoxModelImportForm) . - -#### version 2.0.3 - -* [#60](https://github.com/mlebreuil/netbox-contract/issues/60) Update contract quick search to also filter on fields "External reference" and "Comments". -* [#49](https://github.com/mlebreuil/netbox-contract/issues/49) Manage permissions. - -#### version 2.0.4 - -* Add bulk update capability for contract assignement -* [#63](https://github.com/mlebreuil/netbox-contract/issues/63) Correct an API issue on the invoice object. -* [#64](https://github.com/mlebreuil/netbox-contract/issues/64) Add hierarchy to contract; New parent field created. -* [#65](https://github.com/mlebreuil/netbox-contract/issues/65) Add end date to contact import form. -* Removed the possibility of add or modify circuits to contracts. The field becomes read only and will be removed in next major release. -* Make accounting dimensions optional. - -#### version 2.0.5 - -* [#75](https://github.com/mlebreuil/netbox-contract/issues/74) Fix contract assignement for service providers. -* [#73](https://github.com/mlebreuil/netbox-contract/issues/73) Add comment field to contract import form -* [#72](https://github.com/mlebreuil/netbox-contract/issues/72) Add fields to the contract assignement bottom tables -* Remove the 'add' actions from the contract assignment list view - -#### version 2.0.6 -* [#80](https://github.com/mlebreuil/netbox-contract/issues/80) Fix missing fields in the API. - -#### version 2.0.7 -* [#85](https://github.com/mlebreuil/netbox-contract/issues/85) Fix missing fields contract and invoice import and export forms. - -#### version 2.0.8 -* [#91](https://github.com/mlebreuil/netbox-contract/issues/91) Replace deprecated ( in netbox version 3.6) MultipleChoiceField. -* [48](https://github.com/mlebreuil/netbox-contract/issues/48) Allow other plugin to inject visual in contract and invoice forms. -* [89] (https://github.com/mlebreuil/netbox-contract/issues/89) Add contract assignement to virtual machines. - -#### version 2.0.9 -* [42](https://github.com/mlebreuil/netbox-contract/issues/42) Allow the selection of either providers or Service providers as contract third partie. -* Removed all reference to the direct assignement of circuits to contracts -* [88](https://github.com/mlebreuil/netbox-contract/issues/88) Add a placeholder value to the accounting dimensions jsonfield. This placeholder vale con be configured as part of the PLUGINS_CONFIG parameter in the configuration.py file (see above) -* [89](https://github.com/mlebreuil/netbox-contract/issues/89) add the posibility to link contracts to sites and virtual machines. -* [99](https://github.com/mlebreuil/netbox-contract/issues/99) list child contracts in on the parent view. -#### version 2.0.10 -* [107](https://github.com/mlebreuil/netbox-contract/issues/107) Add the contacts tab to the service provider detail view. -* [111](https://github.com/mlebreuil/netbox-contract/issues/111) Correct assignment spelling. -#### version 2.0.11 -* [115](https://github.com/mlebreuil/netbox-contract/issues/115) API correction for contract external partie -* [117](https://github.com/mlebreuil/netbox-contract/issues/117) Tenant and accounting dimensions optional -* [119](https://github.com/mlebreuil/netbox-contract/issues/119) Add a Yearly recuring cost, read only, calculated field for contract -* [15](https://github.com/mlebreuil/netbox-contract/issues/105) Quick serach limited to active contracts -#### version 2.0.13 -* [123](https://github.com/mlebreuil/netbox-contract/issues/123) prepare plugin to [Netbox 4.0 migration](https://docs.netbox.dev/en/feature/plugins/development/migration-v4/). -* [125](https://github.com/mlebreuil/netbox-contract/issues/125) Cleanup direct reference to Circuits in the Contract model. Correct database inconsistencies related to the ContractAssignment object renaming. - -#### version 2.0.14 - -* [127](https://github.com/mlebreuil/netbox-contract/issues/127) Fix contract filtering -* Fix contact assignement. diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 0000000..827df3f --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,3 @@ +{% + include-markdown "../CHANGELOG.md" +%} \ No newline at end of file diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..f9a79cb --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,3 @@ +{% + include-markdown "../CONTRIBUTING.md" +%} diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..925533a --- /dev/null +++ b/docs/index.md @@ -0,0 +1,3 @@ +{% + include-markdown "../README.md" +%} diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..d5c8af6 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,49 @@ +site_name: Netbox-contract NetBox Plugin +site_url: https://github.com/mlebreuil/netbox-contract +repo_url: https://github.com/mlebreuil/netbox-contract +repo_name: netbox-contract +nav: + - Home: index.md + - Contributing: contributing.md + - Changelog: changelog.md +theme: + name: material + language: en + #logo: assets/logo.png + palette: + scheme: preference + primary: indigo + accent: indigo + features: + - navigation.indexes + - navigation.instant + - navigation.tabs.sticky +markdown_extensions: + - attr_list + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - pymdownx.critic + - pymdownx.caret + - pymdownx.mark + - pymdownx.tilde + - pymdownx.tabbed + - attr_list + - pymdownx.arithmatex: + generic: true + - pymdownx.highlight: + linenums: false + - pymdownx.superfences + - pymdownx.inlinehilite + - pymdownx.details + - admonition + - toc: + baselevel: 2 + permalink: true + slugify: !!python/name:pymdownx.slugs.uslugify + - meta +plugins: + - include-markdown + - search: + lang: en + diff --git a/pyproject.toml b/pyproject.toml index 5acd83c..dfd7421 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "netbox-contract" -version = "2.0.14" +version = "2.0.15" authors = [ { name="Marc Lebreuil", email="marc@famillelebreuil.net" }, ] diff --git a/src/netbox_contract/__init__.py b/src/netbox_contract/__init__.py index bb7ad97..1165f8f 100644 --- a/src/netbox_contract/__init__.py +++ b/src/netbox_contract/__init__.py @@ -5,7 +5,7 @@ class ContractsConfig(PluginConfig): name = 'netbox_contract' verbose_name = 'Netbox contract' description = 'Contract management plugin for Netbox' - version = '2.0.14' + version = '2.0.15' author = 'Marc Lebreuil' author_email = 'marc@famillelebreuil.net' base_url = 'contracts'