From 7c9f415107c3bc17e36e073238d852ff123d9260 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Schoentgen?= Date: Thu, 9 Sep 2021 15:52:24 +0200 Subject: [PATCH] Add a workflow to check documentations (#1151) * Add a workflow to check documentations * Fix markdown issues * Install Ruby 2.7 * Finally, handle and fix GitHub templates * Minor improvement in the feature request template * Verbose mode to be sure all files are checked --- .github/ISSUE_TEMPLATE/bug_report.md | 24 +++++++--- .github/ISSUE_TEMPLATE/feature_request.md | 16 +++++-- .github/workflows/documentations.yml | 21 ++++++++ CODE_OF_CONDUCT.md | 4 +- CONTRIBUTING.md | 4 +- Makefile | 5 ++ README.md | 8 ++-- docs/README.md | 58 +++++++++++------------ docs/linter/mdl-styles.rb | 39 +++++++++++++++ setup.py | 1 - tests/test_docs.py | 35 -------------- 11 files changed, 130 insertions(+), 85 deletions(-) create mode 100644 .github/workflows/documentations.yml create mode 100644 docs/linter/mdl-styles.rb delete mode 100644 tests/test_docs.py diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index d3866e84..7e575869 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -7,34 +7,44 @@ assignees: '' --- -**Checklist** +## Checklist - [ ] I've searched for similar issues. - [ ] I'm using the latest version of HTTPie. --- -**What are the steps to reproduce the problem?** +## Minimal reproduction code and steps 1. 2. 3. +--- -**What is the expected result?** +## Expected result +… -**What happens instead?** +--- +## Current result -**Debug output** +… + +--- + +## Debug output Please re-run the command with `--debug`, then copy the entire command & output and paste both below: -``` +```bash $ http --debug ``` +--- -**Provide any additional information, screenshots, or code examples below:** +## Additional information, screenshots, or code examples + +… diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 9de0b160..329c06a2 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -6,19 +6,25 @@ labels: "new, enhancement" assignees: '' --- -**Checklist** + +## Checklist - [ ] I've searched for similar feature requests. --- -**What enhancement would you like to see?** +## Enhancement request +… -**What problem does it solve?** +--- -E.g. “I'm always frustrated when [...]”, “I’m trying to do […] so that […]”. +## Problem it solves +E.g. “I'm always frustrated when […]”, “I’m trying to do […] so that […]”. -**Provide any additional information, screenshots, or code examples below:** +--- +## Additional information, screenshots, or code examples + +… diff --git a/.github/workflows/documentations.yml b/.github/workflows/documentations.yml new file mode 100644 index 00000000..e24acfc9 --- /dev/null +++ b/.github/workflows/documentations.yml @@ -0,0 +1,21 @@ +name: Check documentations + +on: + pull_request: + paths: + - "*.md" + - "**/*.md" + +jobs: + doc: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Setup Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: 2.7 + - name: Install the linter + run: sudo gem install mdl + - name: Check files + run: make doc-check diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 156e1740..973efd8b 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -68,7 +68,7 @@ members of the project's leadership. ## Attribution This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), -version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html +version 1.4, available at For answers to common questions about this code of conduct, see -https://www.contributor-covenant.org/faq + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 76a82062..7dd42c50 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,7 +44,7 @@ Consider also adding a [CHANGELOG](https://github.com/httpie/httpie/blob/master/ #### Getting the code -Go to https://github.com/httpie/httpie and fork the project repository. +Go to and fork the project repository. ```bash # Clone your fork @@ -89,7 +89,7 @@ a hack but it works™.) You should now see `(httpie)` next to your shell prompt, and the `http` command should point to your development copy: -``` +```bash (httpie) ~/Code/httpie $ which http /Users//Code/httpie/venv/bin/http (httpie) ~/Code/httpie $ http --version diff --git a/Makefile b/Makefile index a020d659..94f5fd97 100644 --- a/Makefile +++ b/Makefile @@ -138,6 +138,11 @@ codecov-upload: @echo +doc-check: + @echo $(H1)Running documentations checks$(H1END) + mdl --verbose --git-recurse --style docs/linter/mdl-styles.rb . + + ############################################################################### # Publishing to PyPi ############################################################################### diff --git a/README.md b/README.md index fef370ab..47d0b8b1 100644 --- a/README.md +++ b/README.md @@ -44,25 +44,25 @@ They use simple and natural syntax and provide formatted and colorized output. Hello World: -``` +```bash $ https httpie.io/hello ``` Custom [HTTP method](https://httpie.io/docs#http-method), [HTTP headers](https://httpie.io/docs#http-headers) and [JSON](https://httpie.io/docs#json) data: -``` +```bash $ http PUT pie.dev/put X-API-Token:123 name=John ``` Build and print a request without sending it using [offline mode](https://httpie.io/docs#offline-mode): -``` +```bash $ http --offline pie.dev/post hello=offline ``` Use [GitHub API](https://developer.github.com/v3/issues/comments/#create-a-comment) to post a comment on an [Issue](https://github.com/httpie/httpie/issues/83) with [authentication](https://httpie.io/docs#authentication): -``` +```bash $ http -a USERNAME POST https://api.github.com/repos/httpie/httpie/issues/83/comments body='HTTPie is awesome! :heart:' ``` diff --git a/docs/README.md b/docs/README.md index c7af40a1..959b30e7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -101,7 +101,7 @@ $ apk add httpie $ eopkg install httpie ``` -### Windows, etc. +### Windows, universal A universal installation method (that works on Linux, macOS and Windows, and always provides the latest version) is to use [pip](https://pypi.org/project/pip/): @@ -1474,40 +1474,40 @@ To set a cookie within a Session there are three options: 1. Get a `Set-Cookie` header in a response from a server -```bash -$ http --session=./session.json pie.dev/cookie/set?foo=bar -``` + ```bash + $ http --session=./session.json pie.dev/cookie/set?foo=bar + ``` 2. Set the cookie name and value through the command line as seen in [cookies](#cookies) -```bash -$ http --session=./session.json pie.dev/headers Cookie:foo=bar -``` + ```bash + $ http --session=./session.json pie.dev/headers Cookie:foo=bar + ``` 3. Manually set cookie parameters in the JSON file of the session -```json -{ - "__meta__": { - "about": "HTTPie session file", - "help": "https://httpie.org/doc#sessions", - "httpie": "2.2.0-dev" - }, - "auth": { - "password": null, - "type": null, - "username": null - }, - "cookies": { - "foo": { - "expires": null, - "path": "/", - "secure": false, - "value": "bar" - } - } -} -``` + ```json + { + "__meta__": { + "about": "HTTPie session file", + "help": "https://httpie.org/doc#sessions", + "httpie": "2.2.0-dev" + }, + "auth": { + "password": null, + "type": null, + "username": null + }, + "cookies": { + "foo": { + "expires": null, + "path": "/", + "secure": false, + "value": "bar" + } + } + } + ``` Cookies will be set in the session file with the priority specified above. For example, a cookie set through the command line will overwrite a cookie of the same name stored in the session file. diff --git a/docs/linter/mdl-styles.rb b/docs/linter/mdl-styles.rb new file mode 100644 index 00000000..a5938b72 --- /dev/null +++ b/docs/linter/mdl-styles.rb @@ -0,0 +1,39 @@ +# Load all rules by default +all + +# +# Tweak rules +# + +# MD002 First header should be a top level header +# Because we use HTML to hide them on the website. +exclude_rule 'MD002' + +# MD013 Line length +exclude_rule 'MD013' + +# MD014 Dollar signs used before commands without showing output +exclude_rule 'MD014' + +# Tell the linter to use ordered lists: +# 1. Foo +# 2. Bar +# 3. Baz +# +# Instead of: +# 1. Foo +# 1. Bar +# 1. Baz +rule 'MD029', :style => :ordered + +# MD033 Inline HTML +# TODO: Tweak elements when https://github.com/markdownlint/markdownlint/issues/118 will be done? +exclude_rule 'MD033' + +# MD034 Bare URL used +# TODO: Remove when https://github.com/markdownlint/markdownlint/issues/328 will be fixed. +exclude_rule 'MD034' + +# MD041 First line in file should be a top level header +# Because we use HTML to hide them on the website. +exclude_rule 'MD041' diff --git a/setup.py b/setup.py index d841aa3a..acde80a0 100644 --- a/setup.py +++ b/setup.py @@ -19,7 +19,6 @@ dev_require = [ 'flake8-deprecated', 'flake8-mutable', 'flake8-tuple', - 'mdformat', 'pytest-cov', 'twine', 'wheel', diff --git a/tests/test_docs.py b/tests/test_docs.py deleted file mode 100644 index 9a5afbf7..00000000 --- a/tests/test_docs.py +++ /dev/null @@ -1,35 +0,0 @@ -import os - -import pytest -from httpie.compat import is_windows - -from .utils import TESTS_ROOT - - -ROOT = TESTS_ROOT.parent -SOURCE_DIRECTORIES = [ - 'docs', - 'extras', - 'httpie', - 'tests', -] - - -def md_filenames(): - yield from ROOT.glob('*.md') - for directory in SOURCE_DIRECTORIES: - yield from (ROOT / directory).glob('**/*.md') - - -filenames = sorted(md_filenames()) -assert filenames - - -@pytest.mark.skipif(is_windows and 'CI' in os.environ, - reason='Does not pass on GitHub.') -@pytest.mark.parametrize('filename', filenames) -def test_md_file_syntax(filename): - mdformat = pytest.importorskip('mdformat._cli') - args = ['--end-of-line', 'lf', '--number'] - err = f'Running "python -m mdformat {" ".join(args)} {filename}; git diff" should help.' - assert mdformat.run(args + ['--check', str(filename)]) == 0, err