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

Python package for Turkish Language.

PyTurkce Python package for Turkish Language. Documentation: https://pyturkce.readthedocs.io. Installation pip install pyturkce Usage from pyturkce im

14 Oct 09, 2022

In this Notebook I've build some machine-learning and deep-learning to classify corona virus tweets, in both multi class classification and binary classification.

Hello, This Notebook Contains Example of Corona Virus Tweets Multi Class Classification. - Classes is: Extremely Positive, Positive, Extremely Negativ

3 Dec 06, 2022

Sorce code and datasets for "K-BERT: Enabling Language Representation with Knowledge Graph",

K-BERT Sorce code and datasets for "K-BERT: Enabling Language Representation with Knowledge Graph", which is implemented based on the UER framework. R

834 Jan 09, 2023

A design of MIDI language for music generation task, specifically for Natural Language Processing (NLP) models.

MIDI Language Introduction Reference Paper: Pop Music Transformer: Beat-based Modeling and Generation of Expressive Pop Piano Compositions: code This

3 May 25, 2022

Guide: Finetune GPT2-XL (1.5 Billion Parameters) and GPT-NEO (2.7 B) on a single 16 GB VRAM V100 Google Cloud instance with Huggingface Transformers using DeepSpeed

Guide: Finetune GPT2-XL (1.5 Billion Parameters) and GPT-NEO (2.7 Billion Parameters) on a single 16 GB VRAM V100 Google Cloud instance with Huggingfa

289 Jan 06, 2023

The FinQA dataset from paper: FinQA: A Dataset of Numerical Reasoning over Financial Data

Data and code for EMNLP 2021 paper "FinQA: A Dataset of Numerical Reasoning over Financial Data"

114 Dec 29, 2022

Chatbot with Pytorch, Python & Nextjs

Installation Instructions Make sure that you have Python 3, gcc, venv, and pip installed. Clone the repository $ git clone https://github.com/sahr

0 Dec 11, 2022

jiant is an NLP toolkit

jiant is an NLP toolkit The multitask and transfer learning toolkit for natural language processing research Why should I use jiant? jiant supports mu

1.5k Jan 04, 2023

NLP Text Classification

多标签文本分类任务近年来随着深度学习的发展，模型参数的数量飞速增长。为了训练这些参数，需要更大的数据集来避免过拟合。然而，对于大部分NLP任务来说，构建大规模的标注数据集非常困难（成本过高），特别是对于句法和语义相关的任务。相比之下，大规模的未标注语料库的构建则相对容易。为了利用这些数据，我们可以

1 Nov 11, 2021

A very simple framework for state-of-the-art Natural Language Processing (NLP)

A very simple framework for state-of-the-art NLP. Developed by Humboldt University of Berlin and friends. Flair is: A powerful NLP library. Flair allo

12.3k Jan 02, 2023

Graph Coloring - Weighted Vertex Coloring Problem

Graph Coloring - Weighted Vertex Coloring Problem This project proposes several local searches and an MCTS algorithm for the weighted vertex coloring

1 Jul 08, 2022

PyTorch implementation and pretrained models for XCiT models. See XCiT: Cross-Covariance Image Transformer

Cross-Covariance Image Transformer (XCiT) PyTorch implementation and pretrained models for XCiT models. See XCiT: Cross-Covariance Image Transformer L

605 Jan 02, 2023

multi-label，classifier，text classification，多标签文本分类，文本分类，BERT，ALBERT，multi-label-classification，seq2seq，attention，beam search

30 Dec 12, 2022

Black for Python docstrings and reStructuredText (rst).

Related tags

Overview

Style-Doc

Installation

Usage

Examples

Support and Feedback

Contribution

Code of Conduct

Working Language

Licensing

Comments

--max-len seems mandatory, not optional parameter

How should we "communicate" an error?

Ignore commented-out classes/functions/etc.

Create a git pre-commit hook for style-doc

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

Add option to use config file

Releases(0.2.0)

0.2.0(Aug 12, 2021)

0.1.0(Aug 6, 2021)

0.0.3.dev1(Aug 4, 2021)

0.0.2.dev4(Jul 6, 2021)

Owner

Telekom Open Source Software

Python package for Turkish Language.

In this Notebook I've build some machine-learning and deep-learning to classify corona virus tweets, in both multi class classification and binary classification.

Sorce code and datasets for "K-BERT: Enabling Language Representation with Knowledge Graph",

A design of MIDI language for music generation task, specifically for Natural Language Processing (NLP) models.

Guide: Finetune GPT2-XL (1.5 Billion Parameters) and GPT-NEO (2.7 B) on a single 16 GB VRAM V100 Google Cloud instance with Huggingface Transformers using DeepSpeed

The FinQA dataset from paper: FinQA: A Dataset of Numerical Reasoning over Financial Data

Chatbot with Pytorch, Python & Nextjs

jiant is an NLP toolkit

NLP Text Classification

A very simple framework for state-of-the-art Natural Language Processing (NLP)

Graph Coloring - Weighted Vertex Coloring Problem

PyTorch implementation and pretrained models for XCiT models. See XCiT: Cross-Covariance Image Transformer

multi-label，classifier，text classification，多标签文本分类，文本分类，BERT，ALBERT，multi-label-classification，seq2seq，attention，beam search

Twitter bot that uses NLP models to summarize news articles referenced in a user's twitter timeline

p-tuning for few-shot NLU task

📜 GPT-2 Rhyming Limerick and Haiku models using data augmentation

PyKaldi is a Python scripting layer for the Kaldi speech recognition toolkit.

A library for end-to-end learning of embedding index and retrieval model

txtai: Build AI-powered semantic search applications in Go

Few-shot Natural Language Generation for Task-Oriented Dialog