dyc
document-your-code
pypi i document-your-code
dyc

document-your-code

Document Your Code

by Mohammad Albakri

0.4.0 (see all)
pypi i document-your-code
Readme

Build Status Downloads

DYC is a CLI tool that helps with documenting your source code. It will help keep you alert for new methods that were added and not documented. It also supports to build a reusable docstring template. Just answer the prompt questions in your terminal to see the effect on your files.

  • Keep your Docstrings consistent.
  • Document your DIFF patch.
  • Ease of helping other developers understand your code.

All contributions are welcome. Please follow Development steps to get up and running, all PRs are welcome. Please join our IRC discord channel if interested.

Tech

Installation

$ pip install document-your-code

Usage

This is intended to work on all programming languages. Kicking off with Python as a starter (Only default formatting added). You can override the default settings for python files and extend new formats in dyc.yaml at your root project. Refer to Example and Advanced

To run on all files in a project. Run

$ dyc start

To run on a Git Diff patch. Run

$  dyc diff

To have Docstrings prepended on a method while development. Run the following command

$ dyc diff --watch

In order to bypass the text editor pop-up in the confirmation stage. Run

$ dyc start --skip-confirm

Method Docstring Options

You can also Setup your own customized Docstring Method Formatting in dyc.yaml within formats key

Methods

KeyDescriptionType
ignoreKnown method Names to be ignored from Docstringslist
keywordsThe necessary keyword to search for in a line that triggers actionslist
enabledDetermine if formatting is enabled for the extensionbool
indentIndentation in a method. Limited options ['tab', '2 spaces', '4 spaces']str
indent_contentConfirm if the content of a docstring has to be indented as wellbool
openStarting opener text of a methodstr
closeClose text of a method. This could be the same as opened, but not all languages opening and closing docstrings are samestr
commentsComments symbolsstr
break_after_openDo we add a new line after adding the open strings of a method?bool
break_after_docstringDo we add a new line after adding the docstring?bool
break_before_closeAdd a new line before closing docstrings on a methodbool
words_per_lineHow many words do we add per docstring?int
within_scopeShould the docstring be within the scope of the method or out? Just like JS Method docstringsbool

Arguments

KeyDescriptionType
titleA title for arguments. i.e: "Parameters"str
underlineUnderline the titlebool
add_typeIf true, it will prompt for the argument typebool
inlineAdd docstrings all inline or break within.bool
ignoreArguments to ignore.list
prefixA prefix like "@param".str

Classes Docstring Options

You can also Setup your own customized Docstring Class Formatting in dyc.yaml within formats key

Class

KeyDescriptionType
keywordsThe necessary keyword to search for in a line that triggers actions (default = ["class"])list
enabledDetermine if formatting is enabled for the extensionbool
indentIndentation in a class. Limited options ['tab', '2 spaces', '4 spaces']str
indent_contentConfirm if the content of a docstring has to be indented as wellbool
openStarting opener text of a methodstr
closeClose text of a class. This could be the same as opened, but not all languages opening and closing docstrings are samestr
commentsComments symbolsstr
break_after_openDo we add a new line after adding the open strings of a class?bool
break_after_docstringDo we add a new line after adding the docstring?bool
break_before_closeAdd a new line before closing docstrings on a classbool
words_per_lineHow many words do we add per docstring?int
within_scopeShould the docstring be within the scope of the class or out? Just like JS Method docstringsbool

Parents

KeyDescriptionType
titleA title for arguments. i.e: "Inheritance"str
underlineUnderline the titlebool
inlineAdd docstrings all inline or break within.bool
prefixA prefix like "@parent".str

Top of file Options

// TODO

Example

$ cd myapp/
$ touch example.py
# example.py

def hello(name):
    return "Hello " + name
$ dyc start

Processing Methods

Do you want to document method hello? [y/N]: y

(hello) Method docstring : DYC Greets you

(name) Argument docstring : John Smith
(name) Argument type : str
## CONFIRM: MODIFY DOCSTRING BETWEEN START AND END LINES ONLY

def hello(name):
    ## START
    """
    DYC Greets you
    Parameters
    ----------
    str name: John Smith
    """
    ## END
    return "Hello " + name
~
~
~
$ cat example.py

def hello(name):
    """
    DYC Greets you
    Parameters
    ----------
    str name: John Smith
    """
    return "Hello " + name%

Watch diff flag.

Run in a terminal session where you have project initialized with Git and on unstaged file. This will not work (YET) on untracked files

$ dyc diff --watch

Then on a separate session

vim path/to/file
## Append or add

def auto_document(foo=False):
    return foo

Print output

$ git diff path/to/file

+
+def auto_document(foo=False):
+    """
+    <docstring>
+    Parameters
+    ----------
+    <type> foo: <arg docstring>
+    """
+    return foo

Advanced

$ cd myapp/
$ touch example.py
$ touch dyc.yaml
# example.py

def hello(name):
    return "Hello " + name
# dyc.yaml

formats:
  -
    extension: 'py'
    method:
      indent: 'tab'
      open: "'''"
      close: "'''"
      break_after_open: false
      break_before_close: false
    arguments:
      title: 'My Customized Title'
      underline: true
      add_type: false
      prefix: '@myAppParam'
$ dyc start

Processing Methods

Do you want to document method hello? [y/N]: y

(hello) Method docstring : Greeting Function

(name) Argument docstring : Human Name
## CONFIRM: MODIFY DOCSTRING BETWEEN START AND END LINES ONLY

def hello(name):
        ## START
        '''Greeting Function
        My Customized Title
        -------------------
        @myAppParam  name: Human Name'''
        ## END
    return "Hello " + name
~

Development

Setup

Thank you for taking the time to contribute into this project. It is simple but could be really helpful moving forward to all developers.

To get started.

  1. Fork this repo.
  2. Clone the project.
  3. Setup virtualenv
  4. In the app folder. Run
$ pip install --editable .

Before commiting:

Install the pre-commit hooks

pre-commit install

With docker

  1. docker-compose build
  2. docker-compose run --rm app
  • Do not need pip install --editable .

We use black to maintain a standard format for our code. Contributions must be black formatted to pass CI.

License

MIT ©

Contributors

Find the list of contributors here

GitHub Stars

86

LAST COMMIT

1yr ago

MAINTAINERS

1

CONTRIBUTORS

22

OPEN ISSUES

12

OPEN PRs

6
VersionTagPublished
0.4.0
1yr ago
0.3.0
1yr ago
0.2.3
2yrs ago
0.2.2
2yrs ago
No alternatives found
No tutorials found
Add a tutorial