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
mlebreuil · May 4, 2024 · 270a7e3 · 270a7e3
1 parent a7fbdf9
commit 270a7e3
Show file tree

Hide file tree

Showing 11 changed files with 293 additions and 72 deletions.
diff --git a/.github/workflows/mkdocs.yaml 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
diff --git 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
@@ -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
@@ -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 [email protected]: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
@@ -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
@@ -0,0 +1,3 @@
+{%
+  include-markdown "../CHANGELOG.md"
+%}
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -0,0 +1,3 @@
+{%
+  include-markdown "../CONTRIBUTING.md"
+%}
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,3 @@
+{%
+    include-markdown "../README.md"
+%}
diff --git a/mkdocs.yml 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
@@ -1,6 +1,6 @@
 [project]
 name = "netbox-contract"
-version = "2.0.14"
+version = "2.0.15"
 authors = [
   { name="Marc Lebreuil", email="[email protected]" },
 ]