Any request, issue reporting: maeliza@codist-ai.com

Content

Docly documentation

Beta version

Automatically generate docstrings for your Python functions

python automatic documentation generation codist
jupyter notebook automatic documentation generation codist
docly automatically generates docstrings for python

Setup

ℹ Presently docly works on functions only. It won't work on Class Methods (i.e functions defined inside a class)

Requirements

  • Language: python 3.6+
  • Distributions: Modern Linux (Debian, Ubuntu) and macOs (Mojave 10.14.6 and up)

Install docly

1. Upgrade pip version 

pip install --upgrade pip 
Before pip 19.0-+ the binary distribution of pygit2 was not automatically picked up and docly depends on it.

2. Install setuptools-rust

pip install setuptools-rust

3. Install docly

pip install docly

Optional:  If you do not want the default PyTorch to install (which installs both CPU and GPU version and thus can be very heavy) then before installing docly, issue the following command

pip install torch==1.6.0+cpu -f https://download.pytorch.org/whl/torch_stable.html

⚠ Errors you might encounter

If you are getting an error to build tree-sitter because you do not have gcc installed then you can install it using sudo apt-get install gcc python3-dev for other distros please check here

please install wheel by doing pip install wheel

Running docly, if you get an error message mentionning *** You may need to add PYTHONIOENCODING=utf-8 to your environment ***.
Please set the environment variable like so:
 
$ export PYTHONIOENCODING=utf-8
 
After setting the environment variable, you can run `docly-gen` normally

Command line options

docly-gen supports additional optional parameters to control how it works.

usage: docly-gen [-h] [--no_generate_diff] [--no_generate_args_list]
[--no_print_report] [--run_on_notebooks]
[--docstring_style DOCSTRING_STYLE]
[--config_file CONFIG_FILE]
files [files ...]positional arguments:
files List the files/dirs you want to run it onoptional arguments:
-h, --help show this help message and exit
--no_generate_diff Do not generate the diff. Only prints a report on the
console
--no_generate_args_list
Do not generate argument list in the docstring
--no_print_report Do not prompt to show the report once the diff is
generated
--run_on_notebooks If you want docly to run on notebook (.ipynb) files
(Requires jupytext and defaults false)
--docstring_style DOCSTRING_STYLE
What style of docstring you want [google, numpy,
sphinx]. Defaults to `google` style.
--config_file CONFIG_FILE
Configuration file for docly

Generating documentation

ℹ The first time you run docly-gen it will download docly model. Please wait to the complete download.

.py files documentation

docly-gen /path/to/file_or_folder_with_python_files

Running this command will print out an interactive prompt to ask if you want to see and apply the changes [y/n]. 

By default, this command generates the comment of the function and lists out all arguments declared. To not generate the arguments list please see below.

.ipynb files documentation

To enable jupyter notebook files reading,activate the feature with: 

pip install 'docly[jupyter]'

To run docly on an .ipynb file, activate the command line switch 

docly-gen --run_on_notebooks /path/to/file_or_folder_with_python_files 

and it will automatically pick up any .ipynb notebooks that you have in the path and put comments in them. 

Select the directories to document

You can provide docly-gen with a --config_file optional parameter. It is a simple ini file with the following structure.
You need to create a section called [skipDirs] and then bellow that mention list all the directories one by one.
[skipDirs]
first/dir/to/avoid = *
second/dir/to/avoid = *

The paths can be either absolute path to the dirs or relative path from where you are issuing docly-gen

If you create a file called docly-config.ini in the same top level directory where you are running docly-gen then you won’t need to provide the explicit optional parameter. docly-gen will automatically discover it and will try to treat it as a config file.

Revert changes

If you want to revert the changes we applied then use -- docly-restore

This will bring back ALL the files that we had touched to the exact state before we applied the changes.

--force optional parameter which will enable users to bypass the interactive prompt.

Save generated comments without changing my files

if you just want the above report and not to apply the chages then:

docly-gen --no_generate_diff --print_report /path/to/file_or_folder_with_python_files