Merge lp:~mvo/snappy/snappy-docs-mdlint into lp:~snappy-dev/snappy/snappy-moved-to-github

Proposed by Michael Vogt
Status: Merged
Approved by: John Lenton
Approved revision: 467
Merged at revision: 466
Proposed branch: lp:~mvo/snappy/snappy-docs-mdlint
Merge into: lp:~snappy-dev/snappy/snappy-moved-to-github
Diff against target: 322 lines (+134/-93)
7 files modified
debian/control (+3/-1)
docs/hashes.md (+8/-8)
docs/meta.md (+61/-61)
docs/package-names.md (+1/-1)
docs/security.md (+22/-22)
mdlint.py (+36/-0)
run-checks (+3/-0)
To merge this branch: bzr merge lp:~mvo/snappy/snappy-docs-mdlint
Reviewer Review Type Date Requested Status
Sergio Schvezov Approve
Review via email: mp+259490@code.launchpad.net

Commit message

Add simple markdown lint to ensure the tables are correctly rendered and run as part of "run-checks.sh"

Description of the change

This is mostly a RFC, this branch may be overkill and too simplistic at the same time (how often do you have that!).

When looking at https://code.launchpad.net/~stephen-stewart/snappy/docs-tidy-up-package-metadata/+merge/259050 I was wondering if we should have a mdlint and run it as part of run-checks. This branch does that. The code that does the lint is very simplistic though.

To post a comment you must log in.
Revision history for this message
Sergio Schvezov (sergiusens) wrote :

This looks good, I wonder if we settle with markdown(django) that maybe we should move the rst doc to md as well, in a different MP that is.

I guess there is no such thing as a markdown(django) linter, this should do for this case. I added a teeny comment though.

Revision history for this message
Sergio Schvezov (sergiusens) :
review: Approve
Revision history for this message
Michael Vogt (mvo) wrote :

Thanks Sergio, I think this makes sense and I added exit code handling now.

Revision history for this message
Snappy Tarmac (snappydevtarmac) wrote :

There are additional revisions which have not been approved in review. Please seek review and approval of these new revisions.

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
=== modified file 'debian/control'
--- debian/control 2015-05-08 19:42:00 +0000
+++ debian/control 2015-05-19 14:28:51 +0000
@@ -14,7 +14,9 @@
14 golang-gocheck-dev,14 golang-gocheck-dev,
15 golang-goconfigparser-dev,15 golang-goconfigparser-dev,
16 golang-pb-dev,16 golang-pb-dev,
17 golang-yaml.v2-dev17 golang-yaml.v2-dev,
18 python3,
19 python3-markdown
18Standards-Version: 3.9.620Standards-Version: 3.9.6
19Homepage: https://launchpad.net/snappy21Homepage: https://launchpad.net/snappy
20Vcs-Browser: http://bazaar.launchpad.net/~snappy-dev/snappy/trunk/files22Vcs-Browser: http://bazaar.launchpad.net/~snappy-dev/snappy/trunk/files
2123
=== modified file 'docs/hashes.md'
--- docs/hashes.md 2015-03-26 20:35:57 +0000
+++ docs/hashes.md 2015-05-19 14:28:51 +0000
@@ -6,17 +6,17 @@
6## Format6## Format
77
8The yaml looks like this:8The yaml looks like this:
9 * archive-sha512: the hexdigest of the data.tar.gz9* archive-sha512: the hexdigest of the data.tar.gz
1010
11Then a list of files/directories/symlinks in the tar that are11Then a list of files/directories/symlinks in the tar that are
12described with:12described with:
13 * name: the full path in the archive13* name: the full path in the archive
14 * mode: First char is the type "f" for file, "d" for dir, "l" for14* mode: First char is the type "f" for file, "d" for dir, "l" for
15 symlink. Then the unix permission bits in the form15 symlink. Then the unix permission bits in the form
16 rwxrwxrwx.16 rwxrwxrwx.
17 E.g. a file with mode 0644 is: "frw-r--r--"17 E.g. a file with mode 0644 is: "frw-r--r--"
18 * size: (applies only to files)18* size: (applies only to files)
19 * sha512: (applies only to files) the hexdigest of the file content19* sha512: (applies only to files) the hexdigest of the file content
2020
21## Owner21## Owner
2222
2323
=== modified file 'docs/meta.md'
--- docs/meta.md 2015-05-13 20:41:52 +0000
+++ docs/meta.md 2015-05-19 14:28:51 +0000
@@ -16,70 +16,70 @@
16This file describes the snap package and is the most important file16This file describes the snap package and is the most important file
17for a snap package. The following keys are mandatory:17for a snap package. The following keys are mandatory:
1818
19 * `name`: the name of the snap (only `[a-z0-9][a-z0-9+.-]`)19* `name`: the name of the snap (only `[a-z0-9][a-z0-9+.-]`)
20 * `version`: the version of the snap (only `[a-zA-Z0-9.+~-]` are allowed)20* `version`: the version of the snap (only `[a-zA-Z0-9.+~-]` are allowed)
21 * `vendor`: the vendor of the snap21* `vendor`: the vendor of the snap
2222
23The following keys are optional:23The following keys are optional:
2424
25 * `icon`: a SVG icon for the snap that is displayed in the store25* `icon`: a SVG icon for the snap that is displayed in the store
26 * `explicit-license-agreement`: set to `Y` if the user needs to accept a26* `explicit-license-agreement`: set to `Y` if the user needs to accept a
27 special `meta/license.txt` before the snap can be installed27 special `meta/license.txt` before the snap can be installed
28 * `license-version`: a string that, when it changes and28* `license-version`: a string that, when it changes and
29 `explicit-license-agreement` is `Y`, prompts the user to accept the29 `explicit-license-agreement` is `Y`, prompts the user to accept the
30 license again.30 license again.
31 * `type`: (optional) the type of the snap, can be:31* `type`: (optional) the type of the snap, can be:
32 * `app` - the default if empty32 * `app` - the default if empty
33 * `oem` - a special snap that OEMs can use to customize snappy for33 * `oem` - a special snap that OEMs can use to customize snappy for
34 their hardware34 their hardware
35 * `framework` - a specialized snap that extends the system that other35 * `framework` - a specialized snap that extends the system that other
36 snaps may use36 snaps may use
3737
38 * `architectures`: (optional) a yaml list of supported architectures38* `architectures`: (optional) a yaml list of supported architectures
39 `["all"]` if empty39 `["all"]` if empty
40 * `frameworks`: a list of the frameworks the snap needs as dependencies40* `frameworks`: a list of the frameworks the snap needs as dependencies
4141
42 * `services`: the servies (daemons) that the snap provides42* `services`: the servies (daemons) that the snap provides
43 * `name`: (required) name of the service (only `[a-zA-Z0-9+.-]`)43 * `name`: (required) name of the service (only `[a-zA-Z0-9+.-]`)
44 * `description`: (required) description of the service44 * `description`: (required) description of the service
45 * `start`: (required) the command to start the service45 * `start`: (required) the command to start the service
46 * `stop`: (optional) the command to stop the service46 * `stop`: (optional) the command to stop the service
47 * `stop-timeout`: (optional) the time in seconds to wait for the47 * `stop-timeout`: (optional) the time in seconds to wait for the
48 service to stop48 service to stop
49 * `poststop`: a command that runs after the service has stopped49 * `poststop`: a command that runs after the service has stopped
50 * `caps`: (optional) list of additional security policies to add.50 * `caps`: (optional) list of additional security policies to add.
51 See `security.md` for details51 See `security.md` for details
52 * `security-template`: (optional) alternate security template to use52 * `security-template`: (optional) alternate security template to use
53 instead of `default`. See `security.md` for details53 instead of `default`. See `security.md` for details
54 * `security-override`: (optional) high level overrides to use when54 * `security-override`: (optional) high level overrides to use when
55 `security-template` and `caps` are not55 `security-template` and `caps` are not
56 sufficient. See security.md for details56 sufficient. See security.md for details
57 * `security-policy`: (optional) hand-crafted low-level raw security57 * `security-policy`: (optional) hand-crafted low-level raw security
58 policy to use instead of using default58 policy to use instead of using default
59 template-based security policy. See59 template-based security policy. See
60 security.md for details60 security.md for details
61 * `ports`: (optional) define what ports the service will work61 * `ports`: (optional) define what ports the service will work
62 * `internal`: the ports the service is going to connect to62 * `internal`: the ports the service is going to connect to
63 * `tagname`: a free form name63 * `tagname`: a free form name
64 * `port`: (optional) number/protocol, e.g. `80/tcp`64 * `port`: (optional) number/protocol, e.g. `80/tcp`
65 * `negotiable`: (optional) Y if the app can use a different port65 * `negotiable`: (optional) Y if the app can use a different port
66 * `external`: the ports the service offer to the world66 * `external`: the ports the service offer to the world
67 * `tagname`: a free form name, some names have meaning like "ui"67 * `tagname`: a free form name, some names have meaning like "ui"
68 * `port`: (optional) see above68 * `port`: (optional) see above
69 * `negotiable`: (optional) see above69 * `negotiable`: (optional) see above
70 * `bus-name`: (optional) message bus connection name for the service.70 * `bus-name`: (optional) message bus connection name for the service.
71 May only be specified for snaps of 'type: framework' (see above). See71 May only be specified for snaps of 'type: framework' (see above). See
72 frameworks.md for details.72 frameworks.md for details.
7373
74 * `binaries`: the binaries (executables) that the snap provides74* `binaries`: the binaries (executables) that the snap provides
75 * `name`: (required) the name of the binary, the user will be able to75 * `name`: (required) the name of the binary, the user will be able to
76 call it as $name.$pkgname (only `[a-zA-Z0-9+.-]`)76 call it as $name.$pkgname (only `[a-zA-Z0-9+.-]`)
77 * `exec`: the program that gets executed (can be omited if name points77 * `exec`: the program that gets executed (can be omited if name points
78 to a binary already)78 to a binary already)
79 * `caps`: (optional) see entry in `services` (above)79 * `caps`: (optional) see entry in `services` (above)
80 * `security-template`: (optional) see entry in `services` (above)80 * `security-template`: (optional) see entry in `services` (above)
81 * `security-override`: (optional) see entry in `services` (above)81 * `security-override`: (optional) see entry in `services` (above)
82 * `security-policy`: (optional) see entry in `services` (above)82 * `security-policy`: (optional) see entry in `services` (above)
8383
84## license.txt84## license.txt
8585
8686
=== modified file 'docs/package-names.md'
--- docs/package-names.md 2015-04-15 22:03:57 +0000
+++ docs/package-names.md 2015-05-19 14:28:51 +0000
@@ -135,4 +135,4 @@
135becomes the gaming engine, you will need to be pushed out to a different name.135becomes the gaming engine, you will need to be pushed out to a different name.
136136
137## Open questions137## Open questions
138 * Must finalize what the `APP_ID` is going to be (composed? no devname? etc)138* Must finalize what the `APP_ID` is going to be (composed? no devname? etc)
139139
=== modified file 'docs/security.md'
--- docs/security.md 2015-05-12 15:32:03 +0000
+++ docs/security.md 2015-05-19 14:28:51 +0000
@@ -81,14 +81,14 @@
81 Specify `caps: []` to indicate no additional `caps`. When `caps` and81 Specify `caps: []` to indicate no additional `caps`. When `caps` and
82 `security-template` are not specified, `caps` defaults to client networking.82 `security-template` are not specified, `caps` defaults to client networking.
83 Not compatible with `security-override` or `security-policy`.83 Not compatible with `security-override` or `security-policy`.
84 * AppArmor access is deny by default and apps are restricted to their84 * AppArmor access is deny by default and apps are restricted to
85 app-specific directories, libraries, etc (enforcing ro, rw, etc).85 their app-specific directories, libraries, etc (enforcing ro,
86 Additional access beyond what is allowed by the declared `security-template`86 rw, etc). Additional access beyond what is allowed by the
87 is declared via this option87 declared `security-template` is declared via this option
88 * seccomp is deny by default. Enough safe syscalls are allowed so that apps88 * seccomp is deny by default. Enough safe syscalls are allowed so
89 using the declared `security-template` should work. Additional access89 that apps using the declared `security-template` should
90 beyond what is allowed by the `security-template` is declared via this90 work. Additional access beyond what is allowed by the
91 option91 `security-template` is declared via this option
92* `security-template`: (optional) alternate security template to use instead of92* `security-template`: (optional) alternate security template to use instead of
93 `default`. When specified without `caps`, `caps` defaults to being empty. Not93 `default`. When specified without `caps`, `caps` defaults to being empty. Not
94 compatible with `security-override` or `security-policy`.94 compatible with `security-override` or `security-policy`.
@@ -97,13 +97,13 @@
97 [advanced usage](https://wiki.ubuntu.com/SecurityTeam/Specifications/SnappyConfinement)97 [advanced usage](https://wiki.ubuntu.com/SecurityTeam/Specifications/SnappyConfinement)
98 for details. Not compatible with `caps`, `security-template` or98 for details. Not compatible with `caps`, `security-template` or
99 `security-policy`99 `security-policy`
100 * `apparmor: path/to/security.override`100 * `apparmor: path/to/security.override`
101 * `seccomp: path/to/filter.override`101 * `seccomp: path/to/filter.override`
102* `security-policy`: (optional) hand-crafted low-level raw security policy to102* `security-policy`: (optional) hand-crafted low-level raw security policy to
103 use instead of using default template-based security policy. Not compatible103 use instead of using default template-based security policy. Not compatible
104 with `caps`, `security-template` or `security-override`.104 with `caps`, `security-template` or `security-override`.
105 * `apparmor: path/to/profile`105 * `apparmor: path/to/profile`
106 * `seccomp: path/to/filter`106 * `seccomp: path/to/filter`
107107
108Eg, consider the following:108Eg, consider the following:
109109
@@ -199,22 +199,22 @@
199The following is planned:199The following is planned:
200200
201* launcher:201* launcher:
202 * utilize syscall argument filtering202 * utilize syscall argument filtering
203 * setup additional cgroups (tag network traffic, memory)203 * setup additional cgroups (tag network traffic, memory)
204 * setup iptables using cgroup tags (for internal app access)204 * setup iptables using cgroup tags (for internal app access)
205 * drop privileges to uid of service205 * drop privileges to uid of service
206* fine-grained network mediation via AppArmor206* fine-grained network mediation via AppArmor
207* `sockets`: (optional) `AF_UNIX` abstract socket definition for coordinated207* `sockets`: (optional) `AF_UNIX` abstract socket definition for coordinated
208 snap communications. Abstract sockets will be namespaced and yaml is such208 snap communications. Abstract sockets will be namespaced and yaml is such
209 that (client) apps wanting to use the socket don't have to declare anything209 that (client) apps wanting to use the socket don't have to declare anything
210 extra, but they don't have access unless the (server) binary declaring the210 extra, but they don't have access unless the (server) binary declaring the
211 socket says that app is ok).211 socket says that app is ok).
212 * `names`: (optional) list of abstract socket names (`<name>_<binaryname>` is212 * `names`: (optional) list of abstract socket names
213 prepended)213 (`<name>_<binaryname>` is prepended)
214 * `allowed-clients`: `<name>.<namespace>` or `<name>.<namespace>_<binaryname>`214 * `allowed-clients`: `<name>.<namespace>` or
215 (ie, omit version and `binaryname` to allow all from snap215 `<name>.<namespace>_<binaryname>` (ie, omit version and
216 `<name>.<namespace>` or omit version to allow only `binaryname` from snap216 `binaryname` to allow all from snap `<name>.<namespace>` or omit
217 `<name>`)217 version to allow only `binaryname` from snap `<name>`)
218218
219 Eg:219 Eg:
220220
221221
=== added file 'mdlint.py'
--- mdlint.py 1970-01-01 00:00:00 +0000
+++ mdlint.py 2015-05-19 14:28:51 +0000
@@ -0,0 +1,36 @@
1#!/usr/bin/python
2#
3# see http://daringfireball.net/projects/markdown/syntax
4# for the "canonical" reference
5#
6# We support django-markdown which uses python-markdown, see:
7# http://pythonhosted.org/Markdown/
8
9import sys
10
11
12def lint_li(fname, text):
13 """Ensure that the list-items are multiplies of 4"""
14 is_clean = True
15 for i, line in enumerate(text.splitlines()):
16 if line.lstrip().startswith("*") and line.index("*") % 4 != 0:
17 print("%s: line %i list has non-4 spaces indent" % (fname, i))
18 is_clean = False
19 return is_clean
20
21
22def lint(md_files):
23 """lint all md files"""
24 all_clean = True
25 for md in md_files:
26 with open(md) as f:
27 buf = f.read()
28 for fname, func in globals().items():
29 if fname.startswith("lint_"):
30 all_clean &= func(md, buf)
31 return all_clean
32
33
34if __name__ == "__main__":
35 if not lint(sys.argv):
36 sys.exit(1)
037
=== modified file 'run-checks'
--- run-checks 2015-03-27 18:35:24 +0000
+++ run-checks 2015-05-19 14:28:51 +0000
@@ -8,6 +8,9 @@
8 goctest="go test"8 goctest="go test"
9fi9fi
1010
11echo Checking docs
12./mdlint.py docs/*.md
13
11echo Checking formatting14echo Checking formatting
12fmt=$(gofmt -l .)15fmt=$(gofmt -l .)
1316

Subscribers

People subscribed via source and target branches