From d24d210e06a8c0a8e8734da02e95a119d5ad70ee Mon Sep 17 00:00:00 2001 From: EdmundGoodman Date: Fri, 19 Nov 2021 01:45:21 +0000 Subject: [PATCH] Improved documentation, adding more code examples and test case docstrings --- jupylint/_test.py | 4 ++-- jupylint/_test_template.py | 13 ++++++++++- jupylint/jupylint.py | 4 ++-- setup.py | 4 ++-- source/autodoc.rst | 5 ++++- source/conf.py | 2 +- source/usage.rst | 45 ++++++++++++++++++++++++++++++++------ 7 files changed, 61 insertions(+), 16 deletions(-) diff --git a/jupylint/_test.py b/jupylint/_test.py index e78272f..a665db1 100644 --- a/jupylint/_test.py +++ b/jupylint/_test.py @@ -112,7 +112,7 @@ def test_keep_code_file_default(self): self.assertFalse(path.isfile("./.jupylint_tmp_out.py")) def test_keep_code_file_set(self): - """Check that running with the keep flag doesn"t delete the file""" + """Check that running with the keep flag doesn't delete the file""" _ = get_jupylint_output( "python3 ./jupylint_runner.py ./jupylint/test_files/stylish.ipynb ./.jupylint_tmp_out.py --keep".split(" ") ) @@ -133,7 +133,7 @@ def test_pylintrc_inclusion(self): self.assertTrue("Report\n======" in result) def test_pylintrc_not_found(self): - """Check that using a pylintrc file with """ + """Check that using a non-existent pylintrc file will fail""" result = get_jupylint_output( "python3 ./jupylint_runner.py ./jupylint/test_files/stylish.ipynb --rcfile ./jupylint/test_files/no_pylintrc".split(" ") ) diff --git a/jupylint/_test_template.py b/jupylint/_test_template.py index 873c29d..abe358b 100644 --- a/jupylint/_test_template.py +++ b/jupylint/_test_template.py @@ -56,9 +56,20 @@ def test_keep_code_file_default(self): pass def test_keep_code_file_set(self): - """Check that running with the keep flag doesn"t delete the file""" + """Check that running with the keep flag doesn't delete the file""" pass + def test_no_pylintrc_inclusion(self): + """Check that not specifying a pylintrc file won't use one""" + pass + + def test_pylintrc_inclusion(self): + """Check that using a pylintrc file will change the output style""" + pass + + def test_pylintrc_not_found(self): + """Check that using a non-existent pylintrc file will fail""" + pass def get_jupylint_output(command): """Run a command to get its output, abstracting away error handling""" diff --git a/jupylint/jupylint.py b/jupylint/jupylint.py index 26e45d8..9b22c1f 100755 --- a/jupylint/jupylint.py +++ b/jupylint/jupylint.py @@ -14,7 +14,7 @@ __copyright__ = "Copyright 2021" __credits__ = ["Edmund Goodman"] __license__ = "MIT" -__version__ = "2.2.1" +__version__ = "2.2.2" __maintainer__ = "Edmund Goodman" __email__ = "egoodman3141@gmail.com" __status__ = "Production" @@ -116,7 +116,7 @@ def run(): def main(): - """External run hook""" + """External run hook for more convenient interfacing within python""" Jupylint.run() diff --git a/setup.py b/setup.py index 7af7346..5c8a3eb 100644 --- a/setup.py +++ b/setup.py @@ -6,7 +6,7 @@ setup( name = 'jupylint', - version = '2.2.1', + version = '2.2.2', license='MIT', description = 'A tool to run pylint on Jupyter notebooks', long_description=long_description, @@ -14,7 +14,7 @@ author = 'Edmund Goodman', author_email = 'egoodman3141@gmail.com', url = 'https://github.com/EdmundGoodman/Jupyter_Pylinter', - download_url = 'https://github.com/EdmundGoodman/Jupyter_Pylinter/archive/refs/tags/v2.2.1.tar.gz', + download_url = 'https://github.com/EdmundGoodman/Jupyter_Pylinter/archive/refs/tags/v2.2.2.tar.gz', packages=find_packages(), entry_points = { "console_scripts": ['jupylint = jupylint.jupylint:main'] diff --git a/source/autodoc.rst b/source/autodoc.rst index 63b12a2..76d3ce5 100644 --- a/source/autodoc.rst +++ b/source/autodoc.rst @@ -7,7 +7,6 @@ Interface .. automodule:: jupylint - Jupylint object --------------- @@ -17,6 +16,8 @@ Jupylint object :special-members: :show-inheritance: +.. autofunction:: main + Unit tests ---------- @@ -28,3 +29,5 @@ Unit tests :private-members: :special-members: :show-inheritance: + +.. autofunction:: get_jupylint_output diff --git a/source/conf.py b/source/conf.py index 1241067..a5d4e5e 100644 --- a/source/conf.py +++ b/source/conf.py @@ -22,7 +22,7 @@ author = 'Edmund Goodman' # The full version, including alpha/beta/rc tags -release = '2.2.1' +release = '2.2.2' # -- General configuration --------------------------------------------------- diff --git a/source/usage.rst b/source/usage.rst index 04c9d37..5fbde64 100644 --- a/source/usage.rst +++ b/source/usage.rst @@ -14,15 +14,36 @@ Linting a file from the command line .. code-block:: bash - jupylint ./in.ipynb + jupylint -Getting help from the command line ----------------------------------- +Saving the raw python extracted from the notebook for linting +------------------------------------------------------------- .. code-block:: bash - jupylint --help + jupylint -k + jupylint --keep + + # The destination of the saved file can also be specified: + jupylint --keep + + +Specifying a custom pylintrc file +--------------------------------- + +.. code-block:: bash + + jupylint --rcfile + + +Getting the version number +-------------------------- + +.. code-block:: bash + + jupylint -v + jupylint --version Getting help from the command line @@ -30,6 +51,7 @@ Getting help from the command line .. code-block:: bash + jupylint -h jupylint --help @@ -38,9 +60,13 @@ Linting a file from within python .. code-block:: python - # All three dictionary keys below are required, but there is - # an additional optional one "rcfile", which specifies the - # location of a pylintrc file to use + # First, we need to import the module + from jupylint import Jupylint + + # The most common use case within python is likely to be manually + # specifying the parameters to run the tool with. + # All three dictionary keys below are required, but there is an additional + # optional one "rcfile", which specifies the location of a pylintrc file args = { "in_file_name": ['./in.ipynb'], "out_file_name": './jupylint_tmp_out.py', @@ -48,3 +74,8 @@ Linting a file from within python } result = Jupylint.execute(args) print(result) + + # Additionally, if the settings are already present as keyword arguments, + # for example using `python - ./in.ipynb`, the tool can be run on those + # arguments using: + Jupylint.run()