From 270a7e3a630dc602764e265e0f44da3b037af0af Mon Sep 17 00:00:00 2001
From: Marc Lebreuil <marc@famillelebreuil.net>
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'