diff --git a/docs/source/contrib.rst b/docs/source/contrib.rst index 560b3c973..6dc4643a9 100644 --- a/docs/source/contrib.rst +++ b/docs/source/contrib.rst @@ -17,23 +17,65 @@ If you like the project and think you could help with making it better, there ar Any contribution would be of great help and I will highly appreciate it! If you have any questions, please create a new issue. -Pre-commit checks ------------------ +Development process +------------------- -Make sure all the tests pass and the code pass the coding standard checks:: +Create a fork of the git repository and checkout a new branch from ``master`` branch. +The branch name may start with an associated issue number so that we can easily +cross-reference them. For example, use ``1234-some-brach-name`` as the name of the branch working to fix issue ``1234``. +Once you're ready to run a full batterie of tests to your changes, open a pull request. - tox -p all +Don't forget to sync your fork once in while to work from the latest revision. -That should be the minimum check to run on your local system. +Pre-commit checks +----------------- + +Make sure all the unit tests pass and the code pass the coding standard checks. + +We use `tox `_ for running our checks, but you can roughly do the same thing from your python environment. + +.. list-table:: Pre-commit checks + :widths: 10 45 45 + :header-rows: 1 + + * - \ + - Using `tox` + - Using your environment + * - Run unit tests + - ``tox -e test`` + - ``pip install '.[test]' && pytest pydoctor`` + * - Run pyflakes + - ``tox -e pyflakes`` + - ``pip install pyflakes && find pydoctor/ -name \*.py ! -path '*/testpackages/*' ! -path '*/sre_parse36.py' ! -path '*/sre_constants36.py' | xargs pyflakes`` + * - Run mypy + - ``tox -e mypy`` + - ``pip install '.[mypy]' && mypy pydoctor`` + * - Run pydoctor on it's own source + - ``tox -e apidocs`` + - ``pip install . && pydoctor --privacy "HIDDEN:pydoctor.test" -q -W pydoctor`` + +These should be the minimum check to run on your local system. A pull request will trigger more tests and most probably there is a tox environment dedicated to that extra test. +Other things hapenning when a PR is open +---------------------------------------- + +- System tests: these tests checks if pydoctor can generate the documentation for a few + specific packages that have been considered as problematic in the past. +- Pydoctor primer: this is to pydoctor what ``mypy_primer`` is to ``mypy``. + It runs pydoctor on a corpus of open source code and compares the output of the application before and after a modification in the code. + Then it reports in comments the result for a PR. The source code of this tool is here: https://github.com/twisted/pydoctor_primer. +- Readthedocs build: For every PR, the sphinx documentation is built and available at ``https://pydoctor--{pr-number}.org.readthedocs.build/en/``. Review process and requirements ------------------------------- - Code changes and code added should have tests: untested code is buggy code. Except special cases, overall test coverage should be increased. - If your pull request is a work in progress, please mark it as draft such that reviewers do not loose time on a PR that is not ready yet. +- There is no strict coding style standard. Since pydoctor is more than 20 years old and we have vendored some code from + other packages as well (namely epydoc and sre_parse), so we can’t really enforce the same style everywhere. It's up to the reviewers + to request refactors when the code is too ugly. - All code changes must be reviewed by at least one person who is not an author of the code being added. This helps prevent bugs from slipping through the net and gives another source for improvements. If the author of the PR is one of the core developers of pydoctor* and no one has reviewed their PR after 9 calendar days, they can review the code changes themselves and proceed with next steps. diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst index 5c128b233..2cd9944ab 100644 --- a/docs/source/quickstart.rst +++ b/docs/source/quickstart.rst @@ -62,6 +62,7 @@ Pydoctor is a pretty verbose tool by default. It’s quite unlikely that you get But don’t worry, pydoctor should have produced useful HTML pages no matter your project design or docstrings. Exit codes includes: + - ``0``: All docstrings are well formatted (warnings may be printed). - ``1``: Pydoctor crashed with traceback (default Python behaviour). - ``2``: Some docstrings are mal formatted. diff --git a/setup.cfg b/setup.cfg index beaa51d75..d4b936967 100644 --- a/setup.cfg +++ b/setup.cfg @@ -71,6 +71,21 @@ test = Sphinx pytest-subtests +mypy = + mypy>=0.902 + mypy-zope + typing-extensions + ; Libraries which include type annotations: + hypothesis + pytest>=6.0.0 + sphinx>=3.4.0 + twisted @ git+https://github.com/twisted/twisted.git + types-requests + ; FIXME: https://github.com/twisted/pydoctor/issues/504 + ; This is pinned for now as newer versions are breaking our static checks. + types-docutils==0.17.5 + types-toml + [options.entry_points] console_scripts = pydoctor = pydoctor.driver:main diff --git a/tox.ini b/tox.ini index 706c60f15..4f402705b 100644 --- a/tox.ini +++ b/tox.ini @@ -64,7 +64,8 @@ commands = [testenv:pyflakes] description = Run pyflakes over the pydoctor code -deps: pyflakes +deps = + pyflakes commands = ; Custom pyflakes run to exlcude some files. The demo packages are trigerring some unused imports warnings. But pydoctor uses those imports to resolve links. So we skip pyflakes for the demo sites. But not the test files. @@ -182,20 +183,8 @@ commands = [testenv:mypy] description = run mypy (static type checker) -deps = - mypy>=0.902 - mypy-zope - typing-extensions - ; Libraries which include type annotations: - hypothesis - pytest>=6.0.0 - sphinx>=3.4.0 - git+https://github.com/twisted/twisted.git - types-requests - # FIXME: https://github.com/twisted/pydoctor/issues/504 - # This is pinned for now as newer versions are breaking our static checks. - types-docutils==0.17.5 - types-toml +extras = + mypy commands = mypy \