diff --git a/docs/source/contributing/check_documentation.rst b/docs/source/contributing/check_documentation.rst new file mode 100644 index 00000000..d94d5e55 --- /dev/null +++ b/docs/source/contributing/check_documentation.rst @@ -0,0 +1,20 @@ +.. _check_documentation: + +Check documentation +------------------- + +1. To build automatic documentation, it is recommended to install the following dependencies: + + .. code-block:: bash + + pip install .[docs] + +2. Documentation files should be located in the `docs/ `_ directory, + which must contain the `docs/source/conf.py `_ (build settings) + and `docs/source/index.rst `_ (documentation main page) files. + +3. Build documentation into HTML pages is done as follows: + + .. code-block:: bash + + python -m sphinx -T -E -W -b html -d docs/_build/doctrees -D language=en docs/source docs/_build diff --git a/docs/source/contributing/contributing.rst b/docs/source/contributing/contributing.rst new file mode 100644 index 00000000..fe349d3b --- /dev/null +++ b/docs/source/contributing/contributing.rst @@ -0,0 +1,61 @@ +.. _contributing: + +Support and Contributing +======================== + +Support +------- +If you are stuck with a problem using Dedoc, please do get in touch at our `Issues `_ (recommend) +or `Dedoc Chat `_. The developers are willing to help. + +You can save time by following this procedure when reporting a problem: + + * Do try to solve the problem on your own first. Read the documentation, including using the search feature, index and reference documentation. + + * Search the issue archives to see if someone else already had the same problem. + + * Before writing, try to create a minimal example that reproduces the problem (with the api parameters and files you used). + You’ll get the fastest response if you can send just a handful of lines of code that show what isn’t working. + + +Contributing Rules +------------------ + + * To add new features to the project repository yourself, you should follow + the `general contributing rules of github `_. + In your Pull Request, set `develop` as the target branch. + + * We recommend using `Pycharm IDE` and `virtualenv` package for development. + + * It is strongly recommended to use in development those versions of libraries that are already used in the project. + Thus, it is necessary to avoid using an excessive number of libraries with the same functionality in the project. + This leads to the growth of the dedoc library image. + + * We strongly recommend using the already used ML library `torch` in development. For example, + using `tensorflow` library instead of `torch` is justified only in case of extreme necessity. + + * If you add new functionality to dedoc, be sure to add python `unitests` to test the added functionality + (you can add api tests in `tests/api_tests `_, + you can add unit tests in `tests/unit_tests `_). + These tests are run automatically in the Continuous Integration pipeline. + + * Before each commit, check the code style using the automatic checker using the `flake8` library. + Instructions for using flake8 are provided here :ref:using_flake8`. + + * We recommend setting up pre-commit for convenience and speeding up development according to the instructions :ref:`using_precommit` . + This will run a style check of the changed code with each commit. + + * In case of any change in the online documentation of the project (for example, when adding a new api parameter), + be sure to check locally that the changed documentation is successfully built and looks as expected. + Building online documentation using `sphinx` is described here :ref:`check_documentation`. + +.. toctree:: + :maxdepth: 1 + + using_flake8 + using_precommit + check_documentation + + + + diff --git a/docs/source/contributing/using_flake8.rst b/docs/source/contributing/using_flake8.rst new file mode 100644 index 00000000..65d4ff8b --- /dev/null +++ b/docs/source/contributing/using_flake8.rst @@ -0,0 +1,19 @@ +.. _using_flake8: + +Using Flake8 (Linting) +---------------------- + +To check Python code for compliance with all style standards, you can use the automatic checking tool `flake8`. +Flake8 checks code according to configuration file `.flake8 `_. + + 1. Install all requirements for `flake8` package: + + .. code-block:: bash + + pip3 install .[lint] + + 2. Run `flake8` package: + + .. code-block:: bash + + flake8 . diff --git a/docs/source/contributing/using_precommit.rst b/docs/source/contributing/using_precommit.rst new file mode 100644 index 00000000..ba73e9ea --- /dev/null +++ b/docs/source/contributing/using_precommit.rst @@ -0,0 +1,28 @@ +.. _using_precommit: + +Using Pre-commit +---------------- + +In addition to running the style check yourself, it is possible to configure a `precommit-hook `_, +which will run the style check before committing (`git commit`). The `pre-commit` is configured in +the `.pre-commit-config.yaml `_ configuration file. + +1. You will need to install the dependency `pre-commit` and set up the hook: + + .. code-block:: bash + + pip3 install pre-commit + pre-commit install + +2. Check the hook (or do `git commit`): + + .. code-block:: bash + + pre-commit run --all + +.. seealso:: + If you want to commit without checking the tests, you need to add the option `--no-verify` + + .. code-block:: bash + + git commit -m "your message" --no-verify diff --git a/docs/source/index.rst b/docs/source/index.rst index fade9141..d9391635 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -282,7 +282,8 @@ This type of structure is configurable (see :ref:`using_patterns`). .. toctree:: :maxdepth: 2 - :caption: Notes + :caption: Development Notes :hidden: + contributing/contributing changelog