search

sagemath / sage

Main repository of SageMath
https://www.sagemath.org
Other
1.34k stars 453 forks source link

src/tox.ini: Add validation of docstrings using flake8-rst-docstrings #30448

Closed mkoeppe closed 2 years ago

mkoeppe commented 4 years ago

Short of running a single-file docbuild (which needs fixing - #30475), there are several options for validating rst files and docstrings:

Here we add a tox environment using https://pypi.org/project/flake8-rst-docstrings.

Usage:

   ./sage -tox -e rst src/sage/geometry/polyhedra

We also run it as part of the Lint workflow on GH Actions (see badge).

Continued in the meta ticket: #34157

Depends on #30503

CC: @tobiasdiez @jhpalmieri @dimpase @fchapoton @DaveWitteMorris @Etn40ff @tscrim @kwankyu

Component: documentation

Author: Matthias Koeppe

Branch/Commit: 0677319

Reviewer: Kwankyu Lee

Issue created by migration from https://trac.sagemath.org/ticket/30448

mkoeppe commented 4 years ago

Description changed:

--- 
+++ 
@@ -1 +1,2 @@
+We could also check some of the patterns that the patchbot complains about - https://github.com/sagemath/sage-patchbot/blob/master/sage_patchbot/plugins.py#L601
mkoeppe commented 4 years ago

Dependencies: #29651

mkoeppe commented 4 years ago

Description changed:

--- 
+++ 
@@ -1,2 +1 @@
-We could also check some of the patterns that the patchbot complains about - https://github.com/sagemath/sage-patchbot/blob/master/sage_patchbot/plugins.py#L601
mkoeppe commented 4 years ago

Changed dependencies from #29651 to #29651, #30475

tobiasdiez commented 4 years ago
comment:5

There are also linters for rst files: rstcheck or doc8

mkoeppe commented 4 years ago
comment:6

Yes, see also my comments in #30415

mkoeppe commented 4 years ago

Description changed:

--- 
+++ 
@@ -1 +1,7 @@
+Short of running a single-file docbuild (which needs fixing - #30475), there are several options for validating rst files and docstrings:

+- rstcheck 
+- doc8
+- https://pypi.org/project/flake8-rst-docstrings
+- ​https://pypi.org/project/flake8-docstrings/ (uses ​https://github.com/pycqa/pydocstyle)
+
mkoeppe commented 4 years ago
comment:7

Replying to @mkoeppe:

Yes, see also my comments in #30415

... added to the description

mkoeppe commented 4 years ago

Changed dependencies from #29651, #30475 to #29651

mkoeppe commented 4 years ago

Changed dependencies from #29651 to #30503

mkoeppe commented 4 years ago

Description changed:

--- 
+++ 
@@ -1,7 +1,7 @@
 Short of running a single-file docbuild (which needs fixing - #30475), there are several options for validating rst files and docstrings:

-- rstcheck 
-- doc8
+- https://pypi.org/project/rstcheck/ 
+- https://pypi.org/project/doc8/
 - https://pypi.org/project/flake8-rst-docstrings
 - ​https://pypi.org/project/flake8-docstrings/ (uses ​https://github.com/pycqa/pydocstyle)
mkoeppe commented 4 years ago

Branch: u/mkoeppe/src_tox_ini__add_validation_of_rst_files_and_docstrings

mkoeppe commented 4 years ago
comment:11

As a first stab at docstring validation, I have added tox -e pydocstyle. This will need some configuration -- right now it gives just too many warnings.

Last 10 new commits:

ca64a52src/tox.ini (codespell): Skip non-English doc, binary files, backup files
d8e101csrc/.codespell-dictionary.txt: New, consider these words correct
e327314src/bin/sage (-advanced): Generalize tox environment list formatting
0847d49tox.ini: When delegating to src/tox.ini, use -- as a separator
2ff2985src/.codespell-ignore.txt: New; use in addition to .codespell-dictionary.txt
92c3b3dtox.ini (codespell): If invoked from SAGE_ROOT, codespell the whole Sage distribution by default
caba287src/tox.ini (codespell): Skip more files and directories
e5a916ftox.ini: Add codespell to envlist
c20fad1Merge branch 't/30503/apply_fossies_codespell' into t/30448/src_tox_ini__add_validation_of_rst_files_and_docstrings
10b6028WIP: src/tox.ini (pydocstyle): New
mkoeppe commented 4 years ago

Commit: 10b6028

tobiasdiez commented 3 years ago
comment:14

For the automated check, it's also a problem that Sage uses a custom doc style and not one of the more standardized ones like pep257, numpy or google. https://www.python.org/dev/peps/pep-0257/ https://numpydoc.readthedocs.io/en/latest/format.html https://google.github.io/styleguide/pyguide.html#383-functions-and-methods

Are there any plans to migrate to one of these standards?

mkoeppe commented 3 years ago
comment:15

I'm not aware of migration plans

jhpalmieri commented 3 years ago
comment:16

Replying to @mkoeppe:

I'm not aware of migration plans

Nor am I, but it's something to consider.

tobiasdiez commented 3 years ago
comment:17

I've created #31044 for this.

mkoeppe commented 3 years ago
comment:18

Also if the decision is made to migrate, to do the actual migration we will certainly need a parser for the sage-style doc.

mkoeppe commented 3 years ago
comment:19

Sage development has entered the release candidate phase for 9.3. Setting a new milestone for this ticket based on a cursory review of ticket status, priority, and last modification date.

7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

d35b85csrc/tox.ini (rst): New, via flake8-rst-docstrings
7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Changed commit from 10b6028 to d35b85c

mkoeppe commented 2 years ago

Description changed:

--- 
+++ 
@@ -5,3 +5,6 @@
 - https://pypi.org/project/flake8-rst-docstrings
 - ​https://pypi.org/project/flake8-docstrings/ (uses ​https://github.com/pycqa/pydocstyle)

+Here we add a tox environment using https://pypi.org/project/flake8-rst-docstrings.
+
+
mkoeppe commented 2 years ago

Author: Matthias Koeppe, ...

mkoeppe commented 2 years ago

Description changed:

--- 
+++ 
@@ -7,4 +7,9 @@

 Here we add a tox environment using https://pypi.org/project/flake8-rst-docstrings.

+Usage:

+```
+   ./sage -tox -e rst src/sage/geometry/polyhedra
+```
+
7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Changed commit from d35b85c to e0ed96b

7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Branch pushed to git repo; I updated commit sha1. New commits:

e0ed96bsrc/tox.ini (flake8): Add to rst-roles, rst-directives, extend-ignore
mkoeppe commented 2 years ago
comment:29

Not sure if we should add all roles from https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html and https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects

7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Changed commit from e0ed96b to 9ee09da

7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Branch pushed to git repo; I updated commit sha1. New commits:

9ee09dasrc/tox.ini (flake8): Add more rst-roles, rst-directives
7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Changed commit from 9ee09da to c0a9940

7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Branch pushed to git repo; I updated commit sha1. New commits:

c0a9940src/tox.ini (flake8): Add more rst-roles
7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Branch pushed to git repo; I updated commit sha1. New commits:

99a17c7.github/workflows/lint.yml: Run tox -e rst
7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Changed commit from c0a9940 to 99a17c7

7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Changed commit from 99a17c7 to 2859d80

7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Branch pushed to git repo; I updated commit sha1. New commits:

2859d80src/tox.ini (flake8): Add more rst-roles
7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Branch pushed to git repo; I updated commit sha1. New commits:

64b6fe8src/sage/geometry/polyhedron/backend_normaliz.py: Fix errors shown by tox -e rst
7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Changed commit from 2859d80 to 64b6fe8

7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Branch pushed to git repo; I updated commit sha1. New commits:

9a57421src/sage/geometry/polyhedron/backend_cdd.py: Fix errors shown by tox -e rst
87ac4e2src/sage/geometry/polyhedron/backend_polymake.py: Fix errors shown by tox -e rst
a09c09asrc/sage/geometry/polyhedron/base3.py: Fix errors shown by tox -e rst
7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Changed commit from 64b6fe8 to a09c09a

7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Changed commit from a09c09a to 05df476

7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Branch pushed to git repo; I updated commit sha1. New commits:

05df476src/sage/schemes: Fix some errors shown by tox -e rst
7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Branch pushed to git repo; I updated commit sha1. New commits:

e459087src/sage/graphs: Fix some errors shown by tox -e rst
7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Changed commit from 05df476 to e459087

7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Changed commit from e459087 to ab4f8dc

7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Branch pushed to git repo; I updated commit sha1. New commits:

ab4f8dcsrc/sage/matrix: Fix errors shown by tox -e rst
7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Branch pushed to git repo; I updated commit sha1. New commits:

1b29e34src/sage/topology: Fix errors shown by tox -e rst
7a2feedsrc/sage/symbolic: Fix errors shown by tox -e rst
a39244fsrc/sage/functions: Fix errors shown by tox -e rst
7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Changed commit from ab4f8dc to a39244f

7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Changed commit from a39244f to 047a845

7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 2 years ago

Branch pushed to git repo; I updated commit sha1. New commits:

047a845src/sage/categories: Fix some errors shown by tox -e rst