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

@@ -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 <COMPLETE ARGUMENT LIST THAT TRIGGERS THE ERROR>
 <COMPLETE OUTPUT>
 ```
 
+---
 
-**Provide any additional information, screenshots, or code examples below:**
+## Additional information, screenshots, or code examples
+
+…

.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
+
+…

.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

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 <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>
 
 For answers to common questions about this code of conduct, see
-https://www.contributor-covenant.org/faq
+<https://www.contributor-covenant.org/faq>

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 <https://github.com/httpie/httpie> 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/<user>/Code/httpie/venv/bin/http
 (httpie) ~/Code/httpie $ http --version

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

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

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,20 +1474,20 @@ 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
-{
+   ```json
+   {
        "__meta__": {
        "about": "HTTPie session file",
        "help": "https://httpie.org/doc#sessions",
@@ -1506,8 +1506,8 @@ $ http --session=./session.json pie.dev/headers Cookie:foo=bar
                "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.

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'

setup.py

@@ -19,7 +19,6 @@ dev_require = [
     'flake8-deprecated',
     'flake8-mutable',
     'flake8-tuple',
-    'mdformat',
     'pytest-cov',
     'twine',
     'wheel',

tests/test_docs.py

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