Skip to content

Commit 4b8cf55

Browse files
stgraberstgraber
authored
Merge pull request #10846 from ru-fu/markdownlint
github: Use markdownlint
2 parents d670138 + db7530c commit 4b8cf55

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

68 files changed

+1240
-528
lines changed

‎.github/workflows/tests.yml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,3 +119,18 @@ jobs:
119119
- name: Build docs and run spellchecker
120120
run: |
121121
make doc-spellcheck
122+
123+
markdownlint:
124+
name: Markdownlint (documentation)
125+
runs-on: ubuntu-latest
126+
steps:
127+
- name: Checkout
128+
uses: actions/checkout@v3
129+
130+
- name: Install mdl
131+
run: |
132+
sudo snap install mdl
133+
134+
- name: Run mdl
135+
run: |
136+
make doc-lint

‎.sphinx/.markdownlint/doc-lint.sh‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
#!/bin/sh -eu
2+
3+
if ! command -v mdl ; then
4+
echo "Install mdl with 'snap install mdl' first.";
5+
exit 1;
6+
fi
7+
8+
## Preprocessing
9+
10+
for fn in $(find doc/ -name '*.md'); do
11+
mkdir -p $(dirname ".tmp/$fn");
12+
sed -E "s/(\(.+\)=)/\1\n/" $fn > .tmp/$fn;
13+
done
14+
15+
trap "rm -rf .tmp/" EXIT
16+
17+
mdl .tmp/doc -s.sphinx/.markdownlint/style.rb -u.sphinx/.markdownlint/rules.rb --ignore-front-matter > .tmp/errors.txt || true
18+
19+
## Postprocessing
20+
21+
while read e; do
22+
e=$(echo "$e" | sed 's/\//\\\//g');
23+
sed -i "/$e/d" .tmp/errors.txt
24+
done <.sphinx/.markdownlint/exceptions.txt
25+
26+
if [ $(wc -l .tmp/errors.txt | awk '{print $1}') = "2" ]; then
27+
echo "Passed!";
28+
exit 0;
29+
else
30+
echo "Failed!";
31+
cat .tmp/errors.txt
32+
exit 1;
33+
fi;

‎.sphinx/.markdownlint/exceptions.txt‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.tmp/doc/authentication.md:61: MD007 Unordered list indentation
2+
.tmp/doc/howto/import_machines_to_instances.md:62: MD034 Bare URL used
3+
.tmp/doc/howto/network_forwards.md:58: MD004 Unordered list style
4+
.tmp/doc/howto/network_forwards.md:62: MD004 Unordered list style
5+
.tmp/doc/howto/network_forwards.md:59: MD005 Inconsistent indentation for list items at the same level
6+
.tmp/doc/howto/network_forwards.md:63: MD005 Inconsistent indentation for list items at the same level
7+
.tmp/doc/howto/network_forwards.md:59: MD032 Lists should be surrounded by blank lines
8+
.tmp/doc/howto/network_forwards.md:63: MD032 Lists should be surrounded by blank lines
9+
.tmp/doc/contributing.md:6: MD002 First header should be a top level header

‎.sphinx/.markdownlint/rules.rb‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
rule 'Myst-MD031', 'Fenced code blocks should be surrounded by blank lines' do
2+
tags :code, :blank_lines
3+
aliases 'blanks-around-fences'
4+
check do |doc|
5+
errors = []
6+
# Some parsers (including kramdown) have trouble detecting fenced code
7+
# blocks without surrounding whitespace, so examine the lines directly.
8+
in_code = false
9+
fence = nil
10+
lines = [''] + doc.lines + ['']
11+
lines.each_with_index do |line, linenum|
12+
line.strip.match(/^(`{3,}|~{3,})/)
13+
unless Regexp.last_match(1) &&
14+
(
15+
!in_code ||
16+
(Regexp.last_match(1).slice(0, fence.length) == fence)
17+
)
18+
next
19+
end
20+
21+
fence = in_code ? nil : Regexp.last_match(1)
22+
in_code = !in_code
23+
if (in_code && !(lines[linenum - 1].empty? || lines[linenum - 1].match(/^[:\-\*]*\s*\% /))) ||
24+
(!in_code && !(lines[linenum + 1].empty? || lines[linenum + 1].match(/^\s*:/)))
25+
errors << linenum
26+
end
27+
end
28+
errors
29+
end
30+
end
31+
32+
33+
rule 'Myst-IDs', 'MyST IDs should be preceded by a blank line' do
34+
check do |doc|
35+
errors = []
36+
ids = doc.matching_text_element_lines(/^\(.+\)=\s*$/)
37+
ids.each do |linenum|
38+
if (linenum > 1) && !doc.lines[linenum - 2].empty?
39+
errors << linenum
40+
end
41+
end
42+
errors.sort
43+
end
44+
end

‎.sphinx/.markdownlint/style.rb‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
all
2+
exclude_rule 'MD013'
3+
exclude_rule 'MD046'
4+
exclude_rule 'MD041'
5+
exclude_rule 'MD040'
6+
exclude_rule 'MD024'
7+
exclude_rule 'MD033'
8+
exclude_rule 'MD022'
9+
exclude_rule 'MD031'
10+
rule 'MD026', :punctuation => '.,;:!'
11+
rule 'MD003', :style => :atx

‎CODE_OF_CONDUCT.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Contributor Covenant Code of Conduct
2+
23
## Our Pledge
4+
35
In the interest of fostering an open and welcoming environment, we as
46
contributors and maintainers pledge to making participation in our project and
57
our community a harassment-free experience for everyone, regardless of age, body
@@ -8,6 +10,7 @@ level of experience, education, socio-economic status, nationality, personal
810
appearance, race, religion, or sexual identity and orientation.
911

1012
## Our Standards
13+
1114
Examples of behavior that contributes to creating a positive environment
1215
include:
1316

@@ -26,6 +29,7 @@ Examples of unacceptable behavior by participants include:
2629
* Other conduct which could reasonably be considered inappropriate in a professional setting
2730

2831
## Our Responsibilities
32+
2933
Project maintainers are responsible for clarifying the standards of acceptable
3034
behavior and are expected to take appropriate and fair corrective action in
3135
response to any instances of unacceptable behavior.
@@ -37,6 +41,7 @@ permanently any contributor for other behaviors that they deem inappropriate,
3741
threatening, offensive, or harmful.
3842

3943
## Scope
44+
4045
This Code of Conduct applies both within project spaces and in public spaces
4146
when an individual is representing the project or its community. Examples of
4247
representing a project or community include using an official project e-mail
@@ -45,6 +50,7 @@ representative at an online or offline event. Representation of a project may be
4550
further defined and clarified by project maintainers.
4651

4752
## Enforcement
53+
4854
Instances of abusive, harassing, or otherwise unacceptable behavior may be
4955
reported by contacting the project team at maintainers@linuxcontainers.org. All
5056
complaints will be reviewed and investigated and will result in a response that
@@ -57,9 +63,10 @@ faith may face temporary or permanent repercussions as determined by other
5763
members of the project's leadership.
5864

5965
## Attribution
66+
6067
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
61-
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
68+
available at <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>
6269

6370
[homepage]: https://www.contributor-covenant.org
6471

65-
For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq
72+
For answers to common questions about this code of conduct, see <https://www.contributor-covenant.org/faq>

‎CONTRIBUTING.md‎

Lines changed: 49 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -3,23 +3,25 @@
33
Check the following guidelines before contributing to the project.
44

55
## Pull requests
6+
67
Changes to this project should be proposed as pull requests on GitHub
78
at: [`https://github.com/lxc/lxd`](https://github.com/lxc/lxd)
89

910
Proposed changes will then go through code review there and once approved,
1011
be merged in the main branch.
1112

1213
## Commit structure
14+
1315
Separate commits should be used for:
1416

15-
- API extension (`api: Add XYZ extension`, contains `doc/api-extensions.md` and `shared/version.api.go`)
16-
- Documentation (`doc: Update XYZ` for files in `doc/`)
17-
- API structure (`shared/api: Add XYZ` for changes to `shared/api/`)
18-
- Go client package (`client: Add XYZ` for changes to `client/`)
19-
- CLI (`lxc/<command>: Change XYZ` for changes to `lxc/`)
20-
- Scripts (`scripts: Update bash completion for XYZ` for changes to `scripts/`)
21-
- LXD daemon (`lxd/<package>: Add support for XYZ` for changes to `lxd/`)
22-
- Tests (`tests: Add test for XYZ` for changes to `tests/`)
17+
- API extension (`api: Add XYZ extension`, contains `doc/api-extensions.md` and `shared/version.api.go`)
18+
- Documentation (`doc: Update XYZ` for files in `doc/`)
19+
- API structure (`shared/api: Add XYZ` for changes to `shared/api/`)
20+
- Go client package (`client: Add XYZ` for changes to `client/`)
21+
- CLI (`lxc/<command>: Change XYZ` for changes to `lxc/`)
22+
- Scripts (`scripts: Update bash completion for XYZ` for changes to `scripts/`)
23+
- LXD daemon (`lxd/<package>: Add support for XYZ` for changes to `lxd/`)
24+
- Tests (`tests: Add test for XYZ` for changes to `tests/`)
2325

2426
The same kind of pattern extends to the other tools in the LXD code tree
2527
and depending on complexity, things may be split into even smaller chunks.
@@ -33,56 +35,59 @@ This structure makes it easier for contributions to be reviewed and also
3335
greatly simplifies the process of back-porting fixes to stable branches.
3436

3537
## License and copyright
38+
3639
By default, any contribution to this project is made under the Apache
3740
2.0 license.
3841

3942
The author of a change remains the copyright holder of their code
4043
(no copyright assignment).
4144

42-
4345
## Developer Certificate of Origin
46+
4447
To improve tracking of contributions to this project we use the DCO 1.1
4548
and use a "sign-off" procedure for all changes going into the branch.
4649

4750
The sign-off is a simple line at the end of the explanation for the
4851
commit which certifies that you wrote it or otherwise have the right
4952
to pass it on as an open-source contribution.
5053

51-
> Developer Certificate of Origin
52-
> Version 1.1
53-
>
54-
> Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
55-
> 660 York Street, Suite 102,
56-
> San Francisco, CA 94110 USA
57-
>
58-
> Everyone is permitted to copy and distribute verbatim copies of this
59-
> license document, but changing it is not allowed.
60-
>
61-
> Developer's Certificate of Origin 1.1
62-
>
63-
> By making a contribution to this project, I certify that:
64-
>
65-
> (a) The contribution was created in whole or in part by me and I
66-
> have the right to submit it under the open source license
67-
> indicated in the file; or
68-
>
69-
> (b) The contribution is based upon previous work that, to the best
70-
> of my knowledge, is covered under an appropriate open source
71-
> license and I have the right under that license to submit that
72-
> work with modifications, whether created in whole or in part
73-
> by me, under the same open source license (unless I am
74-
> permitted to submit under a different license), as indicated
75-
> in the file; or
76-
>
77-
> (c) The contribution was provided directly to me by some other
78-
> person who certified (a), (b) or (c) and I have not modified
79-
> it.
80-
>
81-
> (d) I understand and agree that this project and the contribution
82-
> are public and that a record of the contribution (including all
83-
> personal information I submit with it, including my sign-off) is
84-
> maintained indefinitely and may be redistributed consistent with
85-
> this project or the open source license(s) involved.
54+
```
55+
Developer Certificate of Origin
56+
Version 1.1
57+
58+
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
59+
660 York Street, Suite 102,
60+
San Francisco, CA 94110 USA
61+
62+
Everyone is permitted to copy and distribute verbatim copies of this
63+
license document, but changing it is not allowed.
64+
65+
Developer's Certificate of Origin 1.1
66+
67+
By making a contribution to this project, I certify that:
68+
69+
(a) The contribution was created in whole or in part by me and I
70+
have the right to submit it under the open source license
71+
indicated in the file; or
72+
73+
(b) The contribution is based upon previous work that, to the best
74+
of my knowledge, is covered under an appropriate open source
75+
license and I have the right under that license to submit that
76+
work with modifications, whether created in whole or in part
77+
by me, under the same open source license (unless I am
78+
permitted to submit under a different license), as indicated
79+
in the file; or
80+
81+
(c) The contribution was provided directly to me by some other
82+
person who certified (a), (b) or (c) and I have not modified
83+
it.
84+
85+
(d) I understand and agree that this project and the contribution
86+
are public and that a record of the contribution (including all
87+
personal information I submit with it, including my sign-off) is
88+
maintained indefinitely and may be redistributed consistent with
89+
this project or the open source license(s) involved.
90+
```
8691

8792
An example of a valid sign-off line is:
8893

‎Makefile‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,10 @@ doc-serve:
138138
doc-spellcheck: doc
139139
. $(SPHINXENV) ; python3 -m pyspelling -c .sphinx/.spellcheck.yaml
140140

141+
.PHONY: doc-lint
142+
doc-lint:
143+
.sphinx/.markdownlint/doc-lint.sh
144+
141145
.PHONY: debug
142146
debug:
143147
ifeq "$(TAG_SQLITE3)" ""

‎README.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
[![LXD](https://linuxcontainers.org/static/img/containers.png)](https://linuxcontainers.org/lxd)
22

3-
<!-- Include start LXD intro -->
43
# LXD
4+
5+
<!-- Include start LXD intro -->
6+
57
LXD is a modern, secure and powerful system container and virtual machine manager.
68

79
It provides a unified experience for running and managing full Linux systems inside containers or virtual machines. LXD supplies images for a [wide number of Linux distributions](https://images.linuxcontainers.org) and is built around a very powerful, yet pretty simple, REST API. LXD scales from one instance on a single machine to a cluster in a full data center rack, making it suitable for running workloads both for development and in production.
@@ -22,6 +24,7 @@ Then if you want to run it locally, take a look at our [getting started guide](h
2224
<!-- Include end LXD intro -->
2325

2426
## Status
27+
2528
Type | Service | Status
2629
--- | --- | ---
2730
CI (client) | GitHub | [![Build Status](https://github.com/lxc/lxd/workflows/Client%20build%20and%20unit%20tests/badge.svg)](https://github.com/lxc/lxd/actions)
@@ -34,6 +37,7 @@ Project status | CII Best Practices | [![CII Best Practices](https://bes
3437
<!-- Include start installing -->
3538

3639
## Installing LXD from packages
40+
3741
The LXD daemon only works on Linux but the client tool (`lxc`) is available on most platforms.
3842

3943
OS | Format | Command
@@ -76,28 +80,34 @@ Therefore, you should only give such access to users who you'd trust with root a
7680
The following channels are available for you to interact with the LXD community.
7781

7882
### Bug reports
83+
7984
You can file bug reports and feature requests at: [`https://github.com/lxc/lxd/issues/new`](https://github.com/lxc/lxd/issues/new)
8085

8186
### Forum
87+
8288
A discussion forum is available at: [`https://discuss.linuxcontainers.org`](https://discuss.linuxcontainers.org)
8389

8490
### Mailing lists
91+
8592
We use the LXC mailing lists for developer and user discussions. You can
8693
find and subscribe to those at: [`https://lists.linuxcontainers.org`](https://lists.linuxcontainers.org)
8794

8895
### IRC
96+
8997
If you prefer live discussions, you can find us in [`#lxc`](https://kiwiirc.com/client/irc.libera.chat/#lxc) on `irc.libera.chat`. See [Getting started with IRC](https://discuss.linuxcontainers.org/t/getting-started-with-irc/11920) if needed.
9098

9199
### Commercial support
92100

93101
Commercial support for LXD can be obtained through [Canonical Ltd](https://www.canonical.com).
94102

95103
## Documentation
104+
96105
The official documentation is available at: [`https://linuxcontainers.org/lxd/docs/latest/`](https://linuxcontainers.org/lxd/docs/latest/)
97106

98107
You can find additional resources on the [website](https://linuxcontainers.org/lxd/articles), on [YouTube](https://www.youtube.com/channel/UCuP6xPt0WTeZu32CkQPpbvA) and in the [Tutorials section](https://discuss.linuxcontainers.org/c/tutorials/) in the forum.
99108

100109
<!-- Include end support -->
101110

102111
## Contributing
112+
103113
Fixes and new features are greatly appreciated. Make sure to read our [contributing guidelines](CONTRIBUTING.md) first!

0 commit comments

Comments
 (0)