Black for Python docstrings and reStructuredText (rst).

Last update: Oct 24, 2022

Related tags

Overview

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.

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 Inc. team.

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              The file(s) or folder(s) to restyle.

optional arguments:
  -h, --help         show this help message and exit
  --max_len MAX_LEN  The maximum length of lines.
  --check_only       Whether to only check and not fix styling issues.
  --py_only          Whether to only check py files.
  --rst_only         Whether to 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:

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. By participating in this project, you agree to abide by its Code of Conduct at all times.

Code of Conduct

This project has adopted the Contributor Covenant in version 2.0 as our code of conduct. Please see the details in our CODE_OF_CONDUCT.md. All contributors must abide by the code of conduct.

Working Language

We decided to apply English as the primary project language.

Consequently, all content will be made available primarily in English. We also ask all interested people to use English as language to create issues, in their code (comments, documentation etc.) and when you send requests to us. The application itself and all end-user facing content will be made available in other languages as needed.

Licensing

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.

Comments

--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'

opened by epogrebnyak 2

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...`
enhancement help wanted

opened by PhilipMay 2

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 """.

opened by dragonpaw 2

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.

opened by zaneselvans 1
Fix issues when code has `"""` but is not a docstring

We had to apply this workaround:

https://github.com/telekom/style-doc/blob/db352ed72ae4473a805d485692df58ec4511a673/style_doc/style_doc.py#L495-L497

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

opened by PhilipMay 0
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

enhancement good first issue low priority
opened by PhilipMay 0

Releases(0.2.0)

0.2.0(Aug 12, 2021)
doc improvement

Source code(tar.gz)
Source code(zip)
0.1.0(Aug 6, 2021)

Source code(tar.gz)
Source code(zip)
0.0.3.dev1(Aug 4, 2021)
add default value for --max-len - see https://github.com/telekom/style-doc/issues/19

Source code(tar.gz)
Source code(zip)
0.0.2.dev4(Jul 6, 2021)

Source code(tar.gz)
Source code(zip)

Owner

Telekom Open Source Software

published by Deutsche Telekom AG and partner companies

GitHub Repository

Creating an Audiobook (mp3 file) using a Ebook (epub) using BeautifulSoup and Google Text to Speech

epub2audiobook Creating an Audiobook (mp3 file) using a Ebook (epub) using BeautifulSoup and Google Text to Speech Input examples qual a pasta do seu

7 Aug 25, 2022

Demo programs for the Talking Head Anime from a Single Image 2: More Expressive project.

Demo Code for "Talking Head Anime from a Single Image 2: More Expressive" This repository contains demo programs for the Talking Head Anime

901 Jan 06, 2023

NSFW A chatbot based on GPT2-chitchat

DangBot -- 好怪哦，再来一句卡群怪话bot，powered by GPT2 for Chinese chitchat Training Example: python train.py --lr 5e-2 --epochs 30 --max_len 300 --batch_size 8

11 Jul 21, 2022

超轻量级bert的pytorch版本，大量中文注释，容易修改结构，持续更新

bert4pytorch 2021年8月27更新：感谢大家的star，最近有小伙伴反映了一些小的bug，我也注意到了，奈何这个月工作上实在太忙，更新不及时，大约会在9月中旬集中更新一个只需要pip一下就完全可用的版本，然后会新添加一些关键注释。再增加对抗训练的内容，更新一个完整的finetune

317 Dec 18, 2022

TFIDF-based QA system for AIO2 competition

AIO2 TF-IDF Baseline This is a very simple question answering system, which is developed as a lightweight baseline for AIO2 competition. In the traini

4 Feb 19, 2022

Honor's thesis project analyzing whether the GPT-2 model can more effectively generate free-verse or structured poetry.

gpt2-poetry The following code is for my senior honor's thesis project, under the guidance of Dr. Keith Holyoak at the University of California, Los A

2 Jan 09, 2022

This repository contains the code for EMNLP-2021 paper "Word-Level Coreference Resolution"

Word-Level Coreference Resolution This is a repository with the code to reproduce the experiments described in the paper of the same name, which was a

79 Dec 27, 2022

Code for using and evaluating SpanBERT.

SpanBERT This repository contains code and models for the paper: SpanBERT: Improving Pre-training by Representing and Predicting Spans. If you prefer

798 Dec 30, 2022

Python bot created with Selenium that can guess the daily Wordle word correct 96.8% of the time.

Wordle_Bot Python bot created with Selenium that can guess the daily Wordle word correct 96.8% of the time. It will log onto the wordle website and en

15 Dec 11, 2022

apple's universal binaries BUT MUCH WORSE (PRACTICAL SHITPOST) (NOT PRODUCTION READY)

hyperuniversality investment opportunity: what if we could run multiple architectures in a single file, again apple universal binaries, but worse how

2 Oct 19, 2021

Weird Sort-and-Compress Thing

Weird Sort-and-Compress Thing A weird integer sorting + compression algorithm inspired by a conversation with Luthingx (it probably already exists by

1 Jan 03, 2022

NeMo: a toolkit for conversational AI

NVIDIA NeMo Introduction NeMo is a toolkit for creating Conversational AI applications. NeMo product page. Introductory video. The toolkit comes with

5.3k Jan 04, 2023

Code for the paper "Exploring the Limits of Transfer Learning with a Unified Text-to-Text Transformer"

T5: Text-To-Text Transfer Transformer The t5 library serves primarily as code for reproducing the experiments in Exploring the Limits of Transfer Lear

4.6k Jan 01, 2023

Fully featured implementation of Routing Transformer

Routing Transformer A fully featured implementation of Routing Transformer. The paper proposes using k-means to route similar queries / keys into the

246 Jan 02, 2023

A practical and feature-rich paraphrasing framework to augment human intents in text form to build robust NLU models for conversational engines. Created by Prithiviraj Damodaran. Open to pull requests and other forms of collaboration.

Parrot Parrot is a paraphrase based utterance augmentation framework purpose built to accelerate training NLU models. A paraphrase framework is more t

690 Jan 04, 2023

Amazon Multilingual Counterfactual Dataset (AMCD)

35 Sep 20, 2022

MicBot - MicBot uses Google Translate to speak everyone's chat messages

MicBot MicBot uses Google Translate to speak everyone's chat messages. It can al

2 Mar 09, 2022

End-2-end speech synthesis with recurrent neural networks

Introduction New: Interactive demo using Google Colaboratory can be found here TTS-Cube is an end-2-end speech synthesis system that provides a full p

214 Dec 07, 2022

✔👉A Centralized WebApp to Ensure Road Safety by checking on with the activities of the driver and activating label generator using NLP.

AI-For-Road-Safety Challenge hosted by Omdena Hyderabad Chapter Original Repo Link : https://github.com/OmdenaAI/omdena-india-roadsafety Final Present

7 Nov 29, 2022

Shellcode antivirus evasion framework

Schrodinger's Cat Schrodinger'sCat is a Shellcode antivirus evasion framework Technical principle Please visit my blog https://idiotc4t.com/ How to us

27 Jul 09, 2022