rewrite docstrings to match numpy style guide

README.md

@@ -84,10 +84,32 @@ RAM. These test scripts are in the root of the project, all starting
 with _jenkins-_ since they are run on https://jenkins.debian.net.
 
 
-## Translation
+### Translation
 
 Everything can be translated.  See
 [Translation and Localization](https://f-droid.org/docs/Translation_and_Localization)
 for more info.  
 
 [![translation status](https://hosted.weblate.org/widgets/f-droid/-/fdroidserver/multi-auto.svg)](https://hosted.weblate.org/engage/f-droid/?utm_source=widget)
+
+
+### Documentation
+
+The API documentation based on the docstrings gets automatically published [here](http://fdroid.gitlab.io/fdroidserver/) on every commit on the `master` branch.
+
+It can be built locally via
+
+```bash
+pip install -e .[docs]
+cd docs
+sphinx-apidoc -o ./source ../fdroidserver -M -e
+sphinx-autogen -o generated source/*.rst   
+make html
+```
+
+To additionally lint the code call
+```bash
+pydocstyle fdroidserver --count
+```
+
+When writing docstrings you should follow the [numpy style guide](https://numpydoc.readthedocs.io/en/latest/format.html).

fdroidserver/apksigcopier.py

@@ -372,7 +372,9 @@ def zip_data(apkfile, count=1024):
     """
     Extract central directory, EOCD, and offsets from ZIP.
 
-    Returns ZipData.
+    Returns 
+    -------
+    ZipData
     """
     with open(apkfile, "rb") as fh:
         fh.seek(-count, os.SEEK_END)
@@ -424,6 +426,7 @@ def do_extract(signed_apk, output_dir, v1_only=NO):
 
     The v1_only parameter controls whether the absence of a v1 signature is
     considered an error or not:
+
     * use v1_only=NO (or v1_only=False) to only accept (v1+)v2/v3 signatures;
     * use v1_only=AUTO (or v1_only=None) to automatically detect v2/v3 signatures;
     * use v1_only=YES (or v1_only=True) to ignore any v2/v3 signatures.
@@ -459,6 +462,7 @@ def do_patch(metadata_dir, unsigned_apk, output_apk, v1_only=NO):
 
     The v1_only parameter controls whether the absence of a v1 signature is
     considered an error or not:
+
     * use v1_only=NO (or v1_only=False) to only accept (v1+)v2/v3 signatures;
     * use v1_only=AUTO (or v1_only=None) to automatically detect v2/v3 signatures;
     * use v1_only=YES (or v1_only=True) to ignore any v2/v3 signatures.
@@ -499,6 +503,7 @@ def do_copy(signed_apk, unsigned_apk, output_apk, v1_only=NO):
 
     The v1_only parameter controls whether the absence of a v1 signature is
     considered an error or not:
+
     * use v1_only=NO (or v1_only=False) to only accept (v1+)v2/v3 signatures;
     * use v1_only=AUTO (or v1_only=None) to automatically detect v2/v3 signatures;
     * use v1_only=YES (or v1_only=True) to ignore any v2/v3 signatures.

fdroidserver/btlog.py

@@ -52,13 +52,13 @@ options = None
 def make_binary_transparency_log(
     repodirs, btrepo='binary_transparency', url=None, commit_title='fdroid update'
 ):
-    '''Log the indexes in a standalone git repo to serve as a "binary
+    """Log the indexes in a standalone git repo to serve as a "binary transparency" log.
-    transparency" log.
 
-    see: https://www.eff.org/deeplinks/2014/02/open-letter-to-tech-companies
+    References
-
+    ----------
-    '''
+    https://www.eff.org/deeplinks/2014/02/open-letter-to-tech-companies
 
+    """
     logging.info('Committing indexes to ' + btrepo)
     if os.path.exists(os.path.join(btrepo, '.git')):
         gitrepo = git.Repo(btrepo)

fdroidserver/build.py

@@ -54,12 +54,18 @@ except ImportError:
 def build_server(app, build, vcs, build_dir, output_dir, log_dir, force):
     """Do a build on the builder vm.
 
-    :param app: app metadata dict
+    Parameters
-    :param build:
+    ----------
-    :param vcs: version control system controller object
+    app
-    :param build_dir: local source-code checkout of app
+        app metadata dict
-    :param output_dir: target folder for the build result
+    build
-    :param force:
+    vcs
+        version control system controller object
+    build_dir
+        local source-code checkout of app
+    output_dir
+        target folder for the build result
+    force
     """
 
     global buildserverid
@@ -830,18 +836,26 @@ def trybuild(app, build, build_dir, output_dir, log_dir, also_check_dir,
     """
     Build a particular version of an application, if it needs building.
 
-    :param output_dir: The directory where the build output will go. Usually
+    Parameters
-       this is the 'unsigned' directory.
+    ----------
-    :param repo_dir: The repo directory - used for checking if the build is
+    output_dir
-       necessary.
+        The directory where the build output will go. 
-    :param also_check_dir: An additional location for checking if the build
+        Usually this is the 'unsigned' directory.
+    repo_dir
+        The repo directory - used for checking if the build is necessary.
+    also_check_dir
+        An additional location for checking if the build
         is necessary (usually the archive repo)
-    :param test: True if building in test mode, in which case the build will
+    test
+        True if building in test mode, in which case the build will
         always happen, even if the output already exists. In test mode, the
         output directory should be a temporary location, not any of the real
         ones.
 
-    :returns: True if the build was done, False if it wasn't necessary.
+    Returns
+    -------
+    Boolean
+        True if the build was done, False if it wasn't necessary.
     """
 
     dest_file = common.get_release_filename(app, build)

setup.cfg

@@ -40,10 +40,16 @@ output_dir = locale
 domain = fdroidserver
 directory = locale
 
-[pycodestyle]
-ignore = E203,W503
-max-line-length = 88
-
 [flake8]
 ignore = E203,W503
 max-line-length = 88
+
+# Settings for docstrings linter
+# we use numpy stlye https://numpydoc.readthedocs.io/en/latest/format.html
+# ignored errors are 
+# * D10*: Missing docstring *
+# * rest are the conventions which are ignored by numpy conventions according to http://www.pydocstyle.org/en/stable/error_codes.html 
+[pydocstyle]
+#convention = numpy # cannot be used in combination with ignore, so we list rules seperately.
+ignore = D100,D101,D102,D103,D104,D105,D106,D107,D203,D212,D213,D402,D413,D415,D416,D417,E203,W503
+max-line-length = 88

setup.py

@@ -96,6 +96,7 @@ setup(name='fdroidserver',
               'sphinx',
               'numpydoc',
               'pydata_sphinx_theme',
+              'pydocstyle',
           ]
       },
       classifiers=[