From ff9873f92c8bf833aa6220d93a935726db05ee13 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 May 2022 19:06:07 +0200 Subject: [PATCH] update support files for docstrings --- ci/check_api_endpoint.py | 4 +- ci/check_js_templates.py | 5 +- ci/check_locale_files.py | 2 +- ci/check_migration_files.py | 2 +- tasks.py | 159 ++++++++---------------------------- 5 files changed, 40 insertions(+), 132 deletions(-) diff --git a/ci/check_api_endpoint.py b/ci/check_api_endpoint.py index dffacfcf3a..0bb5618696 100644 --- a/ci/check_api_endpoint.py +++ b/ci/check_api_endpoint.py @@ -1,6 +1,4 @@ -""" -Test that the root API endpoint is available. -""" +"""Test that the root API endpoint is available.""" import json diff --git a/ci/check_js_templates.py b/ci/check_js_templates.py index 84e5198982..5fd7521c55 100644 --- a/ci/check_js_templates.py +++ b/ci/check_js_templates.py @@ -1,9 +1,6 @@ -""" -Test that the "translated" javascript files to not contain template tags -which need to be determined at "run time". +"""Test that the "translated" javascript files to not contain template tags which need to be determined at "run time". This is because the "translated" javascript files are compiled into the "static" directory. - They should only contain template tags that render static information. """ diff --git a/ci/check_locale_files.py b/ci/check_locale_files.py index 808e3ab797..3bfbd66943 100644 --- a/ci/check_locale_files.py +++ b/ci/check_locale_files.py @@ -1,4 +1,4 @@ -""" Check that there are no database migration files which have not been committed. """ +"""Check that there are no database migration files which have not been committed.""" import subprocess import sys diff --git a/ci/check_migration_files.py b/ci/check_migration_files.py index 2f40d49a9d..24668350be 100644 --- a/ci/check_migration_files.py +++ b/ci/check_migration_files.py @@ -1,4 +1,4 @@ -""" Check that there are no database migration files which have not been committed. """ +"""Check that there are no database migration files which have not been committed.""" import subprocess import sys diff --git a/tasks.py b/tasks.py index 9fa55c4513..f6c5f477d3 100644 --- a/tasks.py +++ b/tasks.py @@ -1,5 +1,3 @@ -# -*- coding: utf-8 -*- - import json import os import pathlib @@ -10,10 +8,7 @@ from invoke import task def apps(): - """ - Returns a list of installed apps - """ - + """Returns a list of installed apps""" return [ 'build', 'common', @@ -30,8 +25,8 @@ def apps(): def localDir(): - """ - Returns the directory of *THIS* file. + """Returns the directory of *THIS* file. + Used to ensure that the various scripts always run in the correct directory. """ @@ -39,30 +34,22 @@ def localDir(): def managePyDir(): - """ - Returns the directory of the manage.py file - """ - + """Returns the directory of the manage.py file""" return os.path.join(localDir(), 'InvenTree') def managePyPath(): - """ - Return the path of the manage.py file - """ - + """Return the path of the manage.py file""" return os.path.join(managePyDir(), 'manage.py') def manage(c, cmd, pty=False): - """ - Runs a given command against django's "manage.py" script. + """Runs a given command against django's "manage.py" script. Args: c - Command line context cmd - django command to run """ - c.run('cd "{path}" && python3 manage.py {cmd}'.format( path=managePyDir(), cmd=cmd @@ -71,10 +58,7 @@ def manage(c, cmd, pty=False): @task def plugins(c): - """ - Installs all plugins as specified in 'plugins.txt' - """ - + """Installs all plugins as specified in 'plugins.txt'""" from InvenTree.InvenTree.config import get_plugin_file plugin_file = get_plugin_file() @@ -87,10 +71,7 @@ def plugins(c): @task(post=[plugins]) def install(c): - """ - Installs required python packages - """ - + """Installs required python packages""" print("Installing required python packages from 'requirements.txt'") # Install required Python packages with PIP @@ -99,10 +80,7 @@ def install(c): @task def setup_dev(c): - """ - Sets up everything needed for the dev enviroment - """ - + """Sets up everything needed for the dev enviroment""" print("Installing required python packages from 'requirements.txt'") # Install required Python packages with PIP @@ -117,82 +95,55 @@ def setup_dev(c): @task def shell(c): - """ - Open a python shell with access to the InvenTree database models. - """ - + """Open a python shell with access to the InvenTree database models.""" manage(c, 'shell', pty=True) @task def superuser(c): - """ - Create a superuser (admin) account for the database. - """ - + """Create a superuser/admin account for the database.""" manage(c, 'createsuperuser', pty=True) @task def check(c): - """ - Check validity of django codebase - """ - + """Check validity of django codebase""" manage(c, "check") @task def wait(c): - """ - Wait until the database connection is ready - """ - + """Wait until the database connection is ready""" return manage(c, "wait_for_db") @task(pre=[wait]) def worker(c): - """ - Run the InvenTree background worker process - """ - + """Run the InvenTree background worker process""" manage(c, 'qcluster', pty=True) @task def rebuild_models(c): - """ - Rebuild database models with MPTT structures - """ - + """Rebuild database models with MPTT structures""" manage(c, "rebuild_models", pty=True) @task def rebuild_thumbnails(c): - """ - Rebuild missing image thumbnails - """ - + """Rebuild missing image thumbnails""" manage(c, "rebuild_thumbnails", pty=True) @task def clean_settings(c): - """ - Clean the setting tables of old settings - """ - + """Clean the setting tables of old settings""" manage(c, "clean_settings") @task(help={'mail': 'mail of the user whos MFA should be disabled'}) def remove_mfa(c, mail=''): - """ - Remove MFA for a user - """ - + """Remove MFA for a user""" if not mail: print('You must provide a users mail') @@ -201,11 +152,10 @@ def remove_mfa(c, mail=''): @task(post=[rebuild_models, rebuild_thumbnails]) def migrate(c): - """ - Performs database migrations. + """Performs database migrations. + This is a critical step if the database schema have been altered! """ - print("Running InvenTree database migrations...") print("========================================") @@ -220,35 +170,28 @@ def migrate(c): @task def static(c): - """ - Copies required static files to the STATIC_ROOT directory, - as per Django requirements. - """ - + """Copies required static files to the STATIC_ROOT directory, as per Django requirements.""" manage(c, "prerender") manage(c, "collectstatic --no-input") @task def translate_stats(c): - """ - Collect translation stats. + """Collect translation stats. + The file generated from this is needed for the UI. """ - path = os.path.join('InvenTree', 'script', 'translation_stats.py') c.run(f'python3 {path}') @task(post=[translate_stats, static]) def translate(c): - """ - Rebuild translation source files. (Advanced use only!) + """Rebuild translation source files. (Advanced use only!) Note: This command should not be used on a local install, it is performed as part of the InvenTree translation toolchain. """ - # Translate applicable .py / .html / .js files manage(c, "makemessages --all -e py,html,js --no-wrap") manage(c, "compilemessages") @@ -256,8 +199,7 @@ def translate(c): @task(pre=[install, migrate, static, clean_settings]) def update(c): - """ - Update InvenTree installation. + """Update InvenTree installation. This command should be invoked after source code has been updated, e.g. downloading new code from GitHub. @@ -270,7 +212,6 @@ def update(c): - static - clean_settings """ - # Recompile the translation files (.mo) # We do not run 'invoke translate' here, as that will touch the source (.po) files too! manage(c, 'compilemessages', pty=True) @@ -278,19 +219,14 @@ def update(c): @task def style(c): - """ - Run PEP style checks against InvenTree sourcecode - """ - + """Run PEP style checks against InvenTree sourcecode""" print("Running PEP style checks...") c.run('flake8 InvenTree') @task def test(c, database=None): - """ - Run unit-tests for InvenTree codebase. - """ + """Run unit-tests for InvenTree codebase.""" # Run sanity check on the django install manage(c, 'check') @@ -300,13 +236,10 @@ def test(c, database=None): @task def coverage(c): - """ - Run code-coverage of the InvenTree codebase, - using the 'coverage' code-analysis tools. + """Run code-coverage of the InvenTree codebase, using the 'coverage' code-analysis tools. Generates a code coverage report (available in the htmlcov directory) """ - # Run sanity check on the django install manage(c, 'check') @@ -321,10 +254,7 @@ def coverage(c): def content_excludes(): - """ - Returns a list of content types to exclude from import/export - """ - + """Returns a list of content types to exclude from import/export""" excludes = [ "contenttypes", "auth.permission", @@ -351,10 +281,7 @@ def content_excludes(): @task(help={'filename': "Output filename (default = 'data.json')"}) def export_records(c, filename='data.json'): - """ - Export all database records to a file - """ - + """Export all database records to a file""" # Get an absolute path to the file if not os.path.isabs(filename): filename = os.path.join(localDir(), filename) @@ -403,10 +330,7 @@ def export_records(c, filename='data.json'): @task(help={'filename': 'Input filename', 'clear': 'Clear existing data before import'}, post=[rebuild_models, rebuild_thumbnails]) def import_records(c, filename='data.json', clear=False): - """ - Import database records from a file - """ - + """Import database records from a file""" # Get an absolute path to the supplied filename if not os.path.isabs(filename): filename = os.path.join(localDir(), filename) @@ -450,12 +374,10 @@ def import_records(c, filename='data.json', clear=False): @task def delete_data(c, force=False): - """ - Delete all database records! + """Delete all database records! Warning: This will REALLY delete all records in the database!! """ - print("Deleting all data from InvenTree database...") if force: @@ -466,8 +388,7 @@ def delete_data(c, force=False): @task(post=[rebuild_models, rebuild_thumbnails]) def import_fixtures(c): - """ - Import fixture data into the database. + """Import fixture data into the database. This command imports all existing test fixture data into the database. @@ -476,7 +397,6 @@ def import_fixtures(c): - Running this command may overwrite existing database data!! - Don't say you were not warned... """ - fixtures = [ # Build model 'build', @@ -515,20 +435,16 @@ def import_fixtures(c): @task(help={'address': 'Server address:port (default=127.0.0.1:8000)'}) def server(c, address="127.0.0.1:8000"): - """ - Launch a (deveopment) server using Django's in-built webserver. + """Launch a (deveopment) server using Django's in-built webserver. Note: This is *not* sufficient for a production installation. """ - manage(c, "runserver {address}".format(address=address), pty=True) @task(post=[translate_stats, static, server]) def test_translations(c): - """ - Add a fictional language to test if each component is ready for translations - """ + """Add a fictional language to test if each component is ready for translations""" import django from django.conf import settings @@ -595,8 +511,5 @@ def test_translations(c): @task def render_js_files(c): - """ - Render templated javascript files (used for static testing). - """ - + """Render templated javascript files (used for static testing).""" manage(c, "test InvenTree.ci_render_js")