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

Implementation of ProteinBERT in Pytorch

ProteinBERT - Pytorch (wip) Implementation of ProteinBERT in Pytorch. Original Repository Install $ pip install protein-bert-pytorch Usage import torc

92 Dec 25, 2022

GNES enables large-scale index and semantic search for text-to-text, image-to-image, video-to-video and any-to-any content form

GNES is Generic Neural Elastic Search, a cloud-native semantic search system based on deep neural network.

1.2k Jan 06, 2023

Dense Passage Retriever - is a set of tools and models for open domain Q&A task.

Dense Passage Retrieval Dense Passage Retrieval (DPR) - is a set of tools and models for state-of-the-art open-domain Q&A research. It is based on the

1.1k Jan 07, 2023

NLPShala , the best IDE for all Natural language processing tasks.

The revolutionary IDE for all NLP (Natural language processing) stuffs on the internet.

3 Aug 08, 2021

LSTM model - IMDB review sentiment analysis

NLP - Movie review sentiment analysis The colab notebook contains the code for building a LSTM Recurrent Neural Network that gives 87-88% accuracy on

1 Jan 29, 2022

Tools to download and cleanup Common Crawl data

cc_net Tools to download and clean Common Crawl as introduced in our paper CCNet. If you found these resources useful, please consider citing: @inproc

483 Jan 02, 2023

Learn meanings behind words is a key element in NLP. This project concentrates on the disambiguation of preposition senses. Therefore, we train a bert-transformer model and surpass the state-of-the-art.

New State-of-the-Art in Preposition Sense Disambiguation Supervisor: Prof. Dr. Alexander Mehler Alexander Henlein Institutions: Goethe University TTLa

4 Apr 06, 2022

Grover is a model for Neural Fake News -- both generation and detectio

Grover is a model for Neural Fake News -- both generation and detection. However, it probably can also be used for other generation tasks.

856 Dec 24, 2022

Incorporating KenLM language model with HuggingFace implementation of Wav2Vec2CTC Model using beam search decoding

Wav2Vec2CTC With KenLM Using KenLM ARPA language model with beam search to decode audio files and show the most probable transcription. Assuming you'v

65 Sep 21, 2022

All the code I wrote for Overwatch-related projects that I still own the rights to.

overwatch_shit.zip This is (eventually) going to contain all the software I wrote during my five-year imprisonment stay playing Overwatch. I'll be add

2 Dec 31, 2021

Transformer related optimization, including BERT, GPT

This repository provides a script and recipe to run the highly optimized transformer-based encoder and decoder component, and it is tested and maintained by NVIDIA.

1.7k Jan 04, 2023

Use PaddlePaddle to reproduce the paper：mT5: A Massively Multilingual Pre-trained Text-to-Text Transformer

MT5_paddle Use PaddlePaddle to reproduce the paper：mT5: A Massively Multilingual Pre-trained Text-to-Text Transformer English | 简体中文 mT5: A Massively

2 Oct 17, 2021

Uncomplete archive of files from the European Nopsled Team

European Nopsled CTF Archive This is an archive of collected material from various Capture the Flag competitions that the European Nopsled team played

4 Nov 24, 2021

Predicting the usefulness of reviews given the review text and metadata surrounding the reviews.

Predicting Yelp Review Quality Table of Contents Introduction Motivation Goal and Central Questions The Data Data Storage and ETL EDA Data Pipeline Da

3 Nov 27, 2022

TweebankNLP - Pre-trained Tweet NLP Pipeline (NER, tokenization, lemmatization, POS tagging, dependency parsing) + Models + Tweebank-NER

TweebankNLP This repo contains the new Tweebank-NER dataset and off-the-shelf Twitter-Stanza pipeline for state-of-the-art Tweet NLP, as described in

84 Dec 20, 2022