telekom/style-doc

Black for Python docstrings and reStructuredText (rst).

Style-Doc

Style-Doc is Black for Python docstrings and reStructuredText (rst). It can be used to format docstrings (Google docstring format) in Python files or reStructuredText.

Style-Doc can handle Linux, Windows and Mac style line endings. The output will nevertheless be convertet to \n Linux line endings.

Table of Contents

• Maintainers
• Installation
• Usage
• Examples
• Support and Feedback
• Reporting Security Vulnerabilities
• Contribution
• Code of Conduct
• Licensing

Maintainers

This project is maintained by the One Conversation team of Deutsche Telekom AG. It is based on the style_doc.py script from the HuggingFace team. Many thanks for your consent to publish it as a standalone package 🤗 ♥.

Installation

Style-Doc is available at the Python Package Index (PyPI). It can be installed with pip:

$ pip install style-doc

Usage

$ style-doc --help
usage: style-doc [-h] [--max_len MAX_LEN] [--check_only] [--py_only]
                 [--rst_only]
                 files [files ...]

positional arguments:
  files              file(s) or folder(s) to restyle

optional arguments:
  -h, --help         show this help message and exit
  --max_len MAX_LEN  maximum length of lines, default: 119
  --check_only       only check and not fix styling issues
  --py_only          only check py files
  --rst_only         only check rst files

Examples

• format all docstrings (.py files) and rst files in the src and docs folder with line length of 99:
  style-doc --max_len 99 src docs
• check all docstrings (.py files) and rst files in the src and docs folder with line length of 99:
  style-doc --max_len 99 --check_only src docs
• format all docstrings (.py files only) in the src folder with line length of 99:
  style-doc --max_len 99 --py_only src
• check all docstrings (.py files only) in the src folder with line length of 99:
  style-doc --max_len 99 --check_only --py_only src
• format all rst files only in the docs folder with line length of 99:
  style-doc --max_len 99 --rst_only docs
• check all rst files only in the docs folder with line length of 99:
  style-doc --max_len 99 --check_only --rst_only docs

To integrate Style-Doc (and more checks) into your GitHub Actions see our static_checks.yml example and our configuration in setup.py.

Support and Feedback

The following channels are available for discussions, feedback, and support requests:

• open an issue in our GitHub repository
• send an e-mail to our open source team

Reporting Security Vulnerabilities

This project is built with security and data privacy in mind to ensure your data is safe. We are grateful for security researchers and users reporting a vulnerability to us, first. To ensure that your request is handled in a timely manner and non-disclosure of vulnerabilities can be assured, please follow the below guideline.

Please do not report security vulnerabilities directly on GitHub. GitHub Issues can be publicly seen and therefore would result in a direct disclosure.

Please address questions about data privacy, security concepts, and other media requests to the [email protected] mailbox.

Contribution

Our commitment to open source means that we are enabling - in fact encouraging - all interested parties to contribute and become part of our developer community.

Contribution and feedback is encouraged and always welcome. For more information about how to contribute, as well as additional contribution information, see our Contribution Guidelines.

Code of Conduct

This project has adopted the Contributor Covenant as our code of conduct. Please see the details in our Contributor Covenant Code of Conduct. All contributors must abide by the code of conduct.

Licensing

Copyright (c) 2020 The HuggingFace Inc. team
Copyright (c) 2021 Philip May, Deutsche Telekom AG

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

style-doc's Issues

Finish documentation

ToDo

• add more info to README
• add CONTRIBUTION
• check setup.py for tags and short documentation
• check GitHub project description

--max-len seems mandatory, not optional parameter

I run style-doc . --check and get an error while ```style-doc . --check `--max-len 80`` works.

The error message is:

  File "c:\users\epogr\anaconda3\lib\site-packages\style_doc\style_doc.py", line 460, in style_docstring 
    if len(docstring) < max_len and "\n" not in docstring:
TypeError: '<' not supported between instances of 'int' and 'NoneType'

Add ignore option on block or line level

add more linting

remove redundant isort config

Very long one line docstrings are not formatted

Finish py and rst only impl.

add option to warn when __init__ has docstring

The constructor should be documented at class level and not at the init function.

Write how we use docstrings for classes and __init__

change from py 3.6+ to py 3.5+

Fix issues when code has `"""` but is not a docstring

We had to apply this workaround:

style-doc/style_doc/style_doc.py

Lines 495 to 497 in db352ed

	# fmt: off
	splits = code.split("\"\"\"")
	# fmt: on

# fmt: off and # fmt: on is needed so black does not convert it back to '"""'.

Ignore commented-out classes/functions/etc.

Currently the search for """ isn't respecting commented out code:

    # For future implementation
    # def base_url(self) -> str:
    #     """
    #     Generate SCIM base url
    #     """
    #     return "https://app.asana.com/api/1.0/scim/"

becomes:

    # For future implementation
    # def base_url(self) -> str:
    #     """
    # Generate SCIM base url #
    """
    #     return "https://app.asana.com/api/1.0/scim/"

Which is a syntax error, since it is uncommenting one of the """.

Sync doc with HPOflow (versioning and pypi action)

• telekom/HPOflow#49
• telekom/HPOflow#50

rst header incorrectly transformed - issues with Windows line endings

Main
====

become

Main ====

after running style-doc and not longer recognised as header. I think this is not intended behaviour.

Add ignore option on file level

Add style-doc checks (Makefile & Action)

Create a git pre-commit hook for style-doc

Have you considered packaging style-doc for use as a git pre-commit hook, and listing it with the pre-commit project? It seems like it would be a great addition, and make it very easy for people to integrate the docstring formatter into their existing workflows and get automatic updates when new releases happen.

Add option to use config file

Use pyproject.toml

see black

• https://github.com/psf/black/blob/7567cdf3b4f32d4fb12bd5ca0da838f7ff252cfc/src/black/files.py#L69
• https://github.com/psf/black/blob/017aafea992ca1c6d7af45d3013af7ddb7fda12a/src/black/__init__.py#L44

How should we "communicate" an error?

"You must not set --py_only and --rst_only at the same time." with sys.exit(1) or -1 or raise ValueError(...

raise ValueError(f"{len(changed)} files should be restyled!") or use ``sys.exit...`

fix tabs in 3rd party notes

Add badges to README

Doc for GitHub Action integration