carltongibson
commented
6 years ago Hey @rpkilby.
Yes. 🙂
Do you already have plans here?
Closed rpkilby closed 2 years ago
carltongibson
commented
6 years ago Hey @rpkilby.
Yes. 🙂
Do you already have plans here?
rpkilby
commented
6 years ago Hm. I'm sure there has to be a simple tabs and whitespace checking tool at there. Beyond that, we might have to delve into js/node-based tooling.
Random list of linty things:
In general, I want linting to be incredibly easy to run. If it can't be configured/managed with tox, I'm not interested in adding it.
Unified or textlint might be a good solution here, since we can pick and choose from what plugins/rules we care about. Alternatively, write-good and similar tools are easy to use, purpose-specific tools that might be simple to string together to produce a good linting setup.
rpkilby
commented
6 years ago Additionally, we might look to see what other large projects do to manage this. e.g., what does Django do?
adrienbrunet
commented
5 years ago I tried https://github.com/mapbox/retext-mapbox-standard (from the recommendations in Write The Docs) and write-good. I also checked what Django uses. (I may have missed something, please check again if you want).
Outputs from both tools below. (More tools could be tested and compared)
To reproduce:
npm install -g @mapbox/retext-mapbox-standard
retext-mapbox-standard docs Here is a short extract of the output:
...
docs/topics/api-clients.md
24:39-24:50 warning Replace “a number of” with “many”, “some” a number of
137:68-137:73 warning Replace “as to” with “about”, “on” as to
137:74-137:80 warning Replace “ensure” with “make sure” ensure
149:32-149:41 warning Replace “Currently” with “now”, or remove it currently
164:10-164:17 warning Replace “however” with “but”, “yet” however
184:1-184:9 warning Remove “There is” there is
211:48-211:57 warning Replace “currently” with “now”, or remove it currently
230:1-230:12 warning Replace “In order to” with “to” in order to
265:16-265:22 warning Replace “obtain” with “get” obtain
308:56-308:66 warning Replace “represents” with “is” represents
313:1-313:12 warning Replace “in order to” with “to” in order to
313:13-313:21 warning Replace “indicate” with “show”, “say”, “state”, “write down” indicate
323:5-323:17 warning Replace “subsequently” with “after”, “later”, “then” subsequently
332:31-332:42 warning Replace “in order to” with “to” in order to
352:1-352:10 warning Replace “Currently” with “now”, or remove it currently
369:6-369:12 warning Replace “modify” with “change” modify
379:89-379:100 warning Replace “in order to” with “to” in order to
409:1-409:12 warning Replace “In order to” with “to” in order to
446:16-446:22 warning Replace “obtain” with “get” obtain
docs/topics/browsable-api.md
3:230-3:237 warning Replace “perform” with “do” perform
8:289-8:293 warning Remove “easy” easy
12:108-12:112 warning Remove “easy” easy
20:87-20:91 warning Remove “easy” easy
38:116-38:122 warning Remove “simply” simply
52:35-52:41 warning Remove “simply” simply
70:1-70:7 warning Replace “All of” with “all” all of
85:1-85:7 warning Replace “All of” with “all” all of
89:55-89:64 warning Replace “component” with “part” component
103:83-103:93 warning Replace “similar to” with “like” similar to
120:48-120:62 warning Replace “whether or not” with “whether” whether or not
132:130-132:136 warning Remove “simply” simply
136:117-136:121 warning Remove “very” very
136:169-136:176 warning Replace “perform” with “do” perform
149:213-149:219 warning Remove “simply” simply
docs/topics/browser-enhancements.md
3:89-3:95 warning Replace “HTTP's” with “HTTPS” HTTPS
7:1-7:12 warning Replace “In order to” with “to” in order to
22:11-22:19 warning Replace “prior to” with “before” prior to
36:11-36:19 warning Replace “prior to” with “before” prior to
48:1-48:9 warning Replace “Prior to” with “before” prior to
docs/topics/documenting-your-api.md
3:34-3:40 warning Replace “all of” with “all” all of
7:80-7:91 warning Replace “a number of” with “many”, “some” a number of
40:75-40:79 warning Replace “i.e.” with “as in” i.e.
44:9-44:15 warning Replace “ensure” with “make sure” ensure
180:11-180:22 warning Replace “a number of” with “many”, “some” a number of
191:29-191:33 warning Remove “very” very
200:308-200:316 warning Remove “there is” there is
200:429-200:436 warning Replace “utilize” with “use” utilize
216:103-216:109 warning Remove “simple” simple
226:68-226:71 warning Replace “api” with “API” API
254:170-254:176 warning Remove “simple” simple
262:168-262:174 warning Remove “simply” simply
274:32-274:43 warning Replace “appropriate” with “proper”, “right”, or remove it appropriate
297:94-297:103 warning Replace “regarding” with “about”, “of”, “on” regarding
299:9-299:15 warning Replace “modify” with “change” modify
320:59-320:70 warning Replace “appropriate” with “proper”, “right”, or remove it appropriate
docs/topics/html-and-forms.md
7:1-7:12 warning Replace “In order to” with “to” in order to
docs/topics/internationalization.md
44:135-44:141 warning Replace “remain” with “stay” remain
48:116-48:122 warning Replace “modify” with “change” modify
63:185-63:191 warning Replace “ensure” with “make sure” ensure
82:37-82:41 warning Remove “just” just
89:202-89:208 warning Remove “simply” simply
103:26-103:37 warning Replace “appropriate” with “proper”, “right”, or remove it appropriate
docs/topics/rest-hypermedia-hateoas.md
7:108-7:114 warning Remove “simply” simply
7:144-7:150 warning Remove “easily” easily
7:224-7:230 warning Remove “simple” simple
25:123-25:127 warning Remove “easy” easy
25:138-25:149 warning Replace “appropriate” with “proper”, “right”, or remove it appropriate
29:12-29:19 warning Replace “evident” with “clear” evident
31:94-31:98 warning Remove “easy” easy
31:108-31:119 warning Replace “appropriate” with “proper”, “right”, or remove it appropriate
35:424-35:430 warning Replace “remain” with “stay” remain
docs/topics/writable-nested-serializers.md
7:145-7:156 warning Replace “appropriate” with “proper”, “right”, or remove it appropriate
9:28-9:32 warning Remove “easy” easy
9:76-9:82 warning Remove “simply” simply
9:136-9:143 warning Replace “However” with “but”, “yet” however
âš 917 warnings
To reproduce:
npm install -g write-good
write-good docs/*/*.md Here is an extract of the output:
...
-------------
at the last moment, when it is instantiated into a set of views, typically by us
^^^^^
"it is" is wordy or unneeded on line 7 at column 85
-------------
the last moment, when it is instantiated into a set of views, typically by using
^^^^^^^^^^^^^^^
"is instantiated" may be passive voice on line 7 at column 88
-------------
rovide the default 'read-only' operations. We're still setting the `queryset` a
^^^^
"only" can weaken meaning on line 24 at column 92
-------------
alizer_class` attributes exactly as we did when we were using regular views, but
^^^^^^^
"exactly" can weaken meaning on line 24 at column 180
-------------
Additionally we also provide an extra `highlight` action.
^^^^^^^^^^^^
"Additionally" can weaken meaning on line 36 at column 8
-------------
the `ModelViewSet` class in order to get the complete set of default read and wr
^^^^^^^^^^^
"in order to" is wordy or unneeded on line 51 at column 46
-------------
ht`. This decorator can be used to add any custom endpoints that don't fit into
^^^^^^^
"be used" may be passive voice on line 53 at column 118
-------------
hange the way url should be constructed, you can include `url_path` as a decorat
^^^^^^^^^^^^^^
"be constructed" may be passive voice on line 57 at column 114
-------------
The handler methods only get bound to the actions when we define the URLConf.
^^^^
"only" can weaken meaning on line 61 at column 20
-------------
otice how we're creating multiple views from each `ViewSet` class, by binding th
^^^^^^^^
"multiple" is wordy or unneeded on line 89 at column 26
-------------
into views and urls can be handled automatically, using a `Router` class. All
^^^^^^^^^^
"be handled" may be passive voice on line 104 at column 188
-------------
wsets with the router is similar to providing a urlpattern. We include two argu
^^^^^^^^^^
"similar to" is wordy or unneeded on line 122 at column 44
-------------
Using viewsets can be a really useful abstraction. It helps ensure that URL con
^^^^^^
"really" can weaken meaning on line 128 at column 24
In docs/tutorial/7-schemas-and-client-libraries.md
=============
be used to drive dynamic client libraries that can interact with the API.
^^^^^^^
"be used" may be passive voice on line 7 at column 0
-------------
In order to provide schema support REST framework uses [Core API][coreapi].
^^^^^^^^^^^
"In order to" is wordy or unneeded on line 11 at column 0
-------------
ion for describing APIs. It is used to provide
^^^^^
"It is" is wordy or unneeded on line 13 at column 58
-------------
for describing APIs. It is used to provide
^^^^^^^
"is used" may be passive voice on line 13 at column 61
-------------
I exposes. It can either be used server-side, or
^^^^^^^
"be used" may be passive voice on line 15 at column 48
-------------
we can simply use the automatic schema generation.
^^^^^^
"simply" can weaken meaning on line 29 at column 7
-------------
`coreapi` python package in order to include an
^^^^^^^^^^^
"in order to" is wordy or unneeded on line 31 at column 52
-------------
nteract with the API. To demonstrate this, let's use the
^^^^^^^^^^^
"demonstrate" is wordy or unneeded on line 78 at column 37
-------------
Now check that it is available on the command line...
^^^^^
"it is" is wordy or unneeded on line 85 at column 15
-------------
yet, so right now we're only able to see the read only
^^^^
"only" can weaken meaning on line 115 at column 49
-------------
nly able to see the read only
^^^^
"only" can weaken meaning on line 115 at column 75
-------------
user. In this case we'll just use basic auth.
^^^^
"just" can weaken meaning on line 149 at column 49
-------------
avascript client library is planned to be released
^^^^^^^^^^
"is planned" may be passive voice on line 199 at column 49
-------------
nt library is planned to be released
^^^^^^^^^^^
"be released" may be passive voice on line 199 at column 63
-------------
-object permissions, and multiple renderer formats.
^^^^^^^^
"multiple" is wordy or unneeded on line 207 at column 223
-------------
lly work our way down to simply using regular Django views.
^^^^^^
"simply" can weaken meaning on line 209 at column 138
-------------
work project, here are a few places you can start:
^^^
"few" is a weasel word on line 215 at column 115
-------------
**Now go build awesome things.**
^^^^^^
"things" can weaken meaning on line 221 at column 23
In docs/tutorial/quickstart.md
=============
that the application has been created within the project directory. Using the pr
^^^^^^^^^^^^
"been created" may be passive voice on line 49 at column 45
-------------
ase and the initial user is created and ready to go, open up the app's directory
^^^^^^^^^^
"is created" may be passive voice on line 59 at column 51
-------------
also use primary key and various other relationships, but hyperlinking is good R
^^^^^^^
"various" is a weasel word on line 80 at column 128
-------------
int that allows users to be viewed or edited.
^^^^^^^^^
"be viewed" may be passive voice on line 93 at column 42
-------------
nt that allows groups to be viewed or edited.
^^^^^^^^^
"be viewed" may be passive voice on line 101 at column 43
-------------
Rather than write multiple views we're grouping together all the common behavior
^^^^^^^^
"multiple" is wordy or unneeded on line 106 at column 18
-------------
We can easily break these down into individual views if we need to, but using vi
^^^^^^
"easily" can weaken meaning on line 108 at column 7
-------------
ganized as well as being very concise.
^^^^
"very" is a weasel word and can weaken meaning on line 108 at column 142
-------------
# Additionally, we include login URLs for the browsable API.
^^^^^^^^^^^^
"Additionally" can weaken meaning on line 123 at column 6
-------------
URL conf for our API, by simply registering the viewsets with a router class.
^^^^^^
"simply" can weaken meaning on line 129 at column 106
-------------
over the API URLs we can simply drop down to using regular class-based views, an
^^^^^^
"simply" can weaken meaning on line 131 at column 56
-------------
Finally, we're including default login and logout views for use with the browsab
^^^^^^^
"Finally" can weaken meaning on line 133 at column 0
-------------
Pagination allows you to control how many objects per page are returned. To enab
^^^^^^^^^^
"Pagination" is repeated on line 136 at column 0
-------------
llows you to control how many objects per page are returned. To enable it add th
^^^^
"many" is a weasel word and can weaken meaning on line 136 at column 37
-------------
ow many objects per page are returned. To enable it add the following lines to `
^^^^^^^^^^^^
"are returned" may be passive voice on line 136 at column 59
These two tools are easy to install and quick to run. They do not check the same rules and seems pretty complementary but it needs some more tweaking. All warnings aren't relevant.
About django, I found that pyenchant and sphinxcontrib-spelling are used (see their tox file), as their names imply, it's all about spelling. I have not found any other tools.
Should one first:
rpkilby
commented
5 years ago It would be better to settle on a pipeline before submitting sweeping docs changes.
tomchristie
commented
2 years ago Unless we have some major docs overhaul at some point in the future I think we can safely close this off as not-planned.
It would be nice to have some minimal docs linting. e.g., ensure that we enforce tabs/spacing consistency.