mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-24 05:11:16 +00:00
Bug 1230962 - Create mach/build system integration for mozlint, r=smacleod
MozReview-Commit-ID: 74ma5uMOphe --HG-- extra : rebase_source : 3b0594650a364ad598fc12cc38f3e4fd916ca26b
This commit is contained in:
Andrew Halberstadt
parent
bb96d51342
commit
0484cb2aa7
@ -57,6 +57,7 @@ SEARCH_PATHS = [
|
||||
'python/mach',
|
||||
'python/mozboot',
|
||||
'python/mozbuild',
|
||||
'python/mozlint',
|
||||
'python/mozversioncontrol',
|
||||
'python/blessings',
|
||||
'python/compare-locales',
|
||||
@ -139,6 +140,7 @@ MACH_MODULES = [
|
||||
'testing/web-platform/mach_commands.py',
|
||||
'testing/xpcshell/mach_commands.py',
|
||||
'tools/docs/mach_commands.py',
|
||||
'tools/lint/mach_commands.py',
|
||||
'tools/mercurial/mach_commands.py',
|
||||
'tools/mach_commands.py',
|
||||
'tools/power/mach_commands.py',
|
||||
|
||||
@ -7,6 +7,7 @@ configobj.pth:python/configobj
|
||||
jsmin.pth:python/jsmin
|
||||
mach.pth:python/mach
|
||||
mozbuild.pth:python/mozbuild
|
||||
mozlint.pth:python/mozlint
|
||||
pymake.pth:build/pymake
|
||||
optional:setup.py:python/psutil:build_ext:--inplace
|
||||
optional:psutil.pth:python/psutil
|
||||
|
||||
@ -14,6 +14,7 @@ SPHINX_PYTHON_PACKAGE_DIRS += [
|
||||
'mach',
|
||||
'mozbuild/mozbuild',
|
||||
'mozbuild/mozpack',
|
||||
'mozlint/mozlint',
|
||||
'mozversioncontrol/mozversioncontrol',
|
||||
]
|
||||
|
||||
@ -75,4 +76,8 @@ PYTHON_UNIT_TESTS += [
|
||||
'mozbuild/mozpack/test/test_packager_unpack.py',
|
||||
'mozbuild/mozpack/test/test_path.py',
|
||||
'mozbuild/mozpack/test/test_unify.py',
|
||||
'mozlint/test/test_formatters.py',
|
||||
'mozlint/test/test_parser.py',
|
||||
'mozlint/test/test_roller.py',
|
||||
'mozlint/test/test_types.py',
|
||||
]
|
||||
|
||||
192
tools/lint/docs/Makefile
Normal file
192
tools/lint/docs/Makefile
Normal file
@ -0,0 +1,192 @@
|
||||
# Makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = sphinx-build
|
||||
PAPER =
|
||||
BUILDDIR = _build
|
||||
|
||||
# User-friendly check for sphinx-build
|
||||
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
|
||||
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
|
||||
endif
|
||||
|
||||
# Internal variables.
|
||||
PAPEROPT_a4 = -D latex_paper_size=a4
|
||||
PAPEROPT_letter = -D latex_paper_size=letter
|
||||
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
|
||||
# the i18n builder cannot share the environment and doctrees with the others
|
||||
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
|
||||
|
||||
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
|
||||
|
||||
help:
|
||||
@echo "Please use \`make <target>' where <target> is one of"
|
||||
@echo " html to make standalone HTML files"
|
||||
@echo " dirhtml to make HTML files named index.html in directories"
|
||||
@echo " singlehtml to make a single large HTML file"
|
||||
@echo " pickle to make pickle files"
|
||||
@echo " json to make JSON files"
|
||||
@echo " htmlhelp to make HTML files and a HTML help project"
|
||||
@echo " qthelp to make HTML files and a qthelp project"
|
||||
@echo " applehelp to make an Apple Help Book"
|
||||
@echo " devhelp to make HTML files and a Devhelp project"
|
||||
@echo " epub to make an epub"
|
||||
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
|
||||
@echo " latexpdf to make LaTeX files and run them through pdflatex"
|
||||
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
|
||||
@echo " text to make text files"
|
||||
@echo " man to make manual pages"
|
||||
@echo " texinfo to make Texinfo files"
|
||||
@echo " info to make Texinfo files and run them through makeinfo"
|
||||
@echo " gettext to make PO message catalogs"
|
||||
@echo " changes to make an overview of all changed/added/deprecated items"
|
||||
@echo " xml to make Docutils-native XML files"
|
||||
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
|
||||
@echo " linkcheck to check all external links for integrity"
|
||||
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
|
||||
@echo " coverage to run coverage check of the documentation (if enabled)"
|
||||
|
||||
clean:
|
||||
rm -rf $(BUILDDIR)/*
|
||||
|
||||
html:
|
||||
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
|
||||
|
||||
dirhtml:
|
||||
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
|
||||
|
||||
singlehtml:
|
||||
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
|
||||
@echo
|
||||
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
|
||||
|
||||
pickle:
|
||||
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
|
||||
@echo
|
||||
@echo "Build finished; now you can process the pickle files."
|
||||
|
||||
json:
|
||||
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
|
||||
@echo
|
||||
@echo "Build finished; now you can process the JSON files."
|
||||
|
||||
htmlhelp:
|
||||
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
|
||||
@echo
|
||||
@echo "Build finished; now you can run HTML Help Workshop with the" \
|
||||
".hhp project file in $(BUILDDIR)/htmlhelp."
|
||||
|
||||
qthelp:
|
||||
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
|
||||
@echo
|
||||
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
|
||||
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
|
||||
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/mozlint.qhcp"
|
||||
@echo "To view the help file:"
|
||||
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/mozlint.qhc"
|
||||
|
||||
applehelp:
|
||||
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
|
||||
@echo
|
||||
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
|
||||
@echo "N.B. You won't be able to view it unless you put it in" \
|
||||
"~/Library/Documentation/Help or install it in your application" \
|
||||
"bundle."
|
||||
|
||||
devhelp:
|
||||
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
|
||||
@echo
|
||||
@echo "Build finished."
|
||||
@echo "To view the help file:"
|
||||
@echo "# mkdir -p $$HOME/.local/share/devhelp/mozlint"
|
||||
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/mozlint"
|
||||
@echo "# devhelp"
|
||||
|
||||
epub:
|
||||
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
|
||||
@echo
|
||||
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
|
||||
|
||||
latex:
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo
|
||||
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
|
||||
@echo "Run \`make' in that directory to run these through (pdf)latex" \
|
||||
"(use \`make latexpdf' here to do that automatically)."
|
||||
|
||||
latexpdf:
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo "Running LaTeX files through pdflatex..."
|
||||
$(MAKE) -C $(BUILDDIR)/latex all-pdf
|
||||
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
|
||||
|
||||
latexpdfja:
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo "Running LaTeX files through platex and dvipdfmx..."
|
||||
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
|
||||
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
|
||||
|
||||
text:
|
||||
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
|
||||
@echo
|
||||
@echo "Build finished. The text files are in $(BUILDDIR)/text."
|
||||
|
||||
man:
|
||||
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
|
||||
@echo
|
||||
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
|
||||
|
||||
texinfo:
|
||||
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
|
||||
@echo
|
||||
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
|
||||
@echo "Run \`make' in that directory to run these through makeinfo" \
|
||||
"(use \`make info' here to do that automatically)."
|
||||
|
||||
info:
|
||||
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
|
||||
@echo "Running Texinfo files through makeinfo..."
|
||||
make -C $(BUILDDIR)/texinfo info
|
||||
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
|
||||
|
||||
gettext:
|
||||
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
|
||||
@echo
|
||||
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
|
||||
|
||||
changes:
|
||||
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
|
||||
@echo
|
||||
@echo "The overview file is in $(BUILDDIR)/changes."
|
||||
|
||||
linkcheck:
|
||||
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
|
||||
@echo
|
||||
@echo "Link check complete; look for any errors in the above output " \
|
||||
"or in $(BUILDDIR)/linkcheck/output.txt."
|
||||
|
||||
doctest:
|
||||
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
|
||||
@echo "Testing of doctests in the sources finished, look at the " \
|
||||
"results in $(BUILDDIR)/doctest/output.txt."
|
||||
|
||||
coverage:
|
||||
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
|
||||
@echo "Testing of coverage in the sources finished, look at the " \
|
||||
"results in $(BUILDDIR)/coverage/python.txt."
|
||||
|
||||
xml:
|
||||
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
|
||||
@echo
|
||||
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
|
||||
|
||||
pseudoxml:
|
||||
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
|
||||
@echo
|
||||
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
|
||||
114
tools/lint/docs/conf.py
Normal file
114
tools/lint/docs/conf.py
Normal file
@ -0,0 +1,114 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# mozlint documentation build configuration file, created by
|
||||
# sphinx-quickstart on Fri Nov 27 17:38:49 2015.
|
||||
#
|
||||
# This file is execfile()d with the current directory set to its
|
||||
# containing dir.
|
||||
|
||||
import sys
|
||||
import os
|
||||
import shlex
|
||||
|
||||
# -- General configuration ------------------------------------------------
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = [
|
||||
'sphinx.ext.autodoc',
|
||||
'sphinx.ext.intersphinx',
|
||||
]
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
||||
# The suffix(es) of source filenames.
|
||||
# You can specify multiple suffix as a list of string:
|
||||
# source_suffix = ['.rst', '.md']
|
||||
source_suffix = '.rst'
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# General information about the project.
|
||||
project = u'mozlint'
|
||||
copyright = u'2015, Andrew Halberstadt'
|
||||
author = u'Andrew Halberstadt'
|
||||
|
||||
# The short X.Y version.
|
||||
version = '0.1.0'
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = '0.1.0'
|
||||
|
||||
# This is also used if you do content translation via gettext catalogs.
|
||||
# Usually you set "language" from the command line for these cases.
|
||||
language = None
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
exclude_patterns = ['_build']
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = 'sphinx'
|
||||
|
||||
# If true, `todo` and `todoList` produce output, else they produce nothing.
|
||||
todo_include_todos = False
|
||||
|
||||
|
||||
# -- Options for HTML output ----------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
html_theme = 'default'
|
||||
|
||||
if os.environ.get('READTHEDOCS', None) != 'True':
|
||||
try:
|
||||
import sphinx_rtd_theme
|
||||
html_theme = 'sphinx_rtd_theme'
|
||||
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
|
||||
except ImportError:
|
||||
pass
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ['_static']
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = 'mozlintdoc'
|
||||
|
||||
# -- Options for LaTeX output ---------------------------------------------
|
||||
|
||||
latex_elements = {}
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title,
|
||||
# author, documentclass [howto, manual, or own class]).
|
||||
latex_documents = [
|
||||
(master_doc, 'mozlint.tex', u'mozlint Documentation',
|
||||
u'Andrew Halberstadt', 'manual'),
|
||||
]
|
||||
|
||||
# -- Options for manual page output ---------------------------------------
|
||||
|
||||
# One entry per manual page. List of tuples
|
||||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = [
|
||||
(master_doc, 'mozlint', u'mozlint Documentation',
|
||||
[author], 1)
|
||||
]
|
||||
|
||||
# -- Options for Texinfo output -------------------------------------------
|
||||
|
||||
# Grouping the document tree into Texinfo files. List of tuples
|
||||
# (source start file, target name, title, author,
|
||||
# dir menu entry, description, category)
|
||||
texinfo_documents = [
|
||||
(master_doc, 'mozlint', u'mozlint Documentation',
|
||||
author, 'mozlint', 'One line description of project.',
|
||||
'Miscellaneous'),
|
||||
]
|
||||
|
||||
# Example configuration for intersphinx: refer to the Python standard library.
|
||||
intersphinx_mapping = {'https://docs.python.org/': None}
|
||||
137
tools/lint/docs/create.rst
Normal file
137
tools/lint/docs/create.rst
Normal file
@ -0,0 +1,137 @@
|
||||
Adding a New Linter to the Tree
|
||||
===============================
|
||||
|
||||
A linter is a python file with a ``.lint`` extension and a global dict called LINTER. Depending on how
|
||||
complex it is, there may or may not be any actual python code alongside the LINTER definition.
|
||||
|
||||
Here's a trivial example:
|
||||
|
||||
no-eval.lint
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
LINTER = {
|
||||
'name': 'EvalLinter',
|
||||
'description': "Ensures the string 'eval' doesn't show up."
|
||||
'include': "**/*.js",
|
||||
'type': 'string',
|
||||
'payload': 'eval',
|
||||
}
|
||||
|
||||
Now ``no-eval.lint`` gets passed into :func:`LintRoller.read`.
|
||||
|
||||
|
||||
Linter Types
|
||||
------------
|
||||
|
||||
There are three types of linters, though more may be added in the future.
|
||||
|
||||
1. string - fails if substring is found
|
||||
2. regex - fails if regex matches
|
||||
3. external - fails if a python function returns a non-empty result list
|
||||
|
||||
As seen from the example above, string and regex linters are very easy to create, but they
|
||||
should be avoided if possible. It is much better to use a context aware linter for the language you
|
||||
are trying to lint. For example, use eslint to lint JavaScript files, use flake8 to lint python
|
||||
files, etc.
|
||||
|
||||
Which brings us to the third and most interesting type of linter, external. External linters call
|
||||
an arbitrary python function which is responsible for not only running the linter, but ensuring the
|
||||
results are structured properly. For example, an external type could shell out to a 3rd party
|
||||
linter, collect the output and format it into a list of :class:`ResultContainer` objects.
|
||||
|
||||
|
||||
LINTER Definition
|
||||
-----------------
|
||||
|
||||
Each ``.lint`` file must have a variable called LINTER which is a dict containing metadata about the
|
||||
linter. Here are the supported keys:
|
||||
|
||||
* name - The name of the linter (required)
|
||||
* description - A brief description of the linter's purpose (required)
|
||||
* type - One of 'string', 'regex' or 'external' (required)
|
||||
* payload - The actual linting logic, depends on the type (required)
|
||||
* include - A list of glob patterns that must be matched (optional)
|
||||
* exclude - A list of glob patterns that must not be matched (optional)
|
||||
* setup - A function that sets up external dependencies (optional)
|
||||
|
||||
In addition to the above, some ``.lint`` files correspond to a single lint rule. For these, the
|
||||
following additional keys may be specified:
|
||||
|
||||
* message - A string to print on infraction (optional)
|
||||
* hint - A string with a clue on how to fix the infraction (optional)
|
||||
* rule - An id string for the lint rule (optional)
|
||||
* level - The severity of the infraction, either 'error' or 'warning' (optional)
|
||||
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
Here is an example of an external linter that shells out to the python flake8 linter:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import json
|
||||
import os
|
||||
import subprocess
|
||||
from collections import defaultdict
|
||||
|
||||
from mozlint import result
|
||||
|
||||
|
||||
FLAKE8_NOT_FOUND = """
|
||||
Could not find flake8! Install flake8 and try again.
|
||||
""".strip()
|
||||
|
||||
|
||||
def lint(files, **lintargs):
|
||||
import which
|
||||
|
||||
binary = os.environ.get('FLAKE8')
|
||||
if not binary:
|
||||
try:
|
||||
binary = which.which('flake8')
|
||||
except which.WhichError:
|
||||
print(FLAKE8_NOT_FOUND)
|
||||
return 1
|
||||
|
||||
# Flake8 allows passing in a custom format string. We use
|
||||
# this to help mold the default flake8 format into what
|
||||
# mozlint's ResultContainer object expects.
|
||||
cmdargs = [
|
||||
binary,
|
||||
'--format',
|
||||
'{"path":"%(path)s","lineno":%(row)s,"column":%(col)s,"rule":"%(code)s","message":"%(text)s"}',
|
||||
] + files
|
||||
|
||||
proc = subprocess.Popen(cmdargs, stdout=subprocess.PIPE, env=os.environ)
|
||||
output = proc.communicate()[0]
|
||||
|
||||
# all passed
|
||||
if not output:
|
||||
return []
|
||||
|
||||
results = []
|
||||
for line in output.splitlines():
|
||||
# res is a dict of the form specified by --format above
|
||||
res = json.loads(line)
|
||||
|
||||
# parse level out of the id string
|
||||
if 'code' in res and res['code'].startswith('W'):
|
||||
res['level'] = 'warning'
|
||||
|
||||
# result.from_linter is a convenience method that
|
||||
# creates a ResultContainer using a LINTER definition
|
||||
# to populate some defaults.
|
||||
results.append(result.from_linter(LINTER, **res))
|
||||
|
||||
return results
|
||||
|
||||
|
||||
LINTER = {
|
||||
'name': "flake8",
|
||||
'description': "Python linter",
|
||||
'include': ['**/*.py'],
|
||||
'type': 'external',
|
||||
'payload': lint,
|
||||
}
|
||||
35
tools/lint/docs/index.rst
Normal file
35
tools/lint/docs/index.rst
Normal file
@ -0,0 +1,35 @@
|
||||
Linting
|
||||
=======
|
||||
|
||||
Linters are used in mozilla-central to help enforce coding style and avoid bad practices. Due to the
|
||||
wide variety of languages in use and the varying style preferences per team, this is not an easy
|
||||
task. In addition, linters should be runnable from editors, from the command line, from review tools
|
||||
and from continuous integration. It's easy to see how the complexity of running all of these
|
||||
different kinds of linters in all of these different places could quickly balloon out of control.
|
||||
|
||||
``Mozlint`` is a library that accomplishes two goals:
|
||||
|
||||
1. It provides a standard method for adding new linters to the tree, which can be as easy as
|
||||
defining a json object in a ``.lint`` file. This helps keep lint related code localized, and
|
||||
prevents different teams from coming up with their own unique lint implementations.
|
||||
2. It provides a streamlined interface for running all linters at once. Instead of running N
|
||||
different lint commands to test your patch, a single ``mach lint`` command will automatically run
|
||||
all applicable linters. This means there is a single API surface that other tools can use to
|
||||
invoke linters.
|
||||
|
||||
``Mozlint`` isn't designed to be used directly by end users. Instead, it can be consumed by things
|
||||
like mach, mozreview and taskcluster.
|
||||
|
||||
.. toctree::
|
||||
:caption: Linting User Guide
|
||||
:maxdepth: 2
|
||||
|
||||
usage
|
||||
create
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
263
tools/lint/docs/make.bat
Normal file
263
tools/lint/docs/make.bat
Normal file
@ -0,0 +1,263 @@
|
||||
@ECHO OFF
|
||||
|
||||
REM Command file for Sphinx documentation
|
||||
|
||||
if "%SPHINXBUILD%" == "" (
|
||||
set SPHINXBUILD=sphinx-build
|
||||
)
|
||||
set BUILDDIR=_build
|
||||
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
|
||||
set I18NSPHINXOPTS=%SPHINXOPTS% .
|
||||
if NOT "%PAPER%" == "" (
|
||||
set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
|
||||
set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
|
||||
)
|
||||
|
||||
if "%1" == "" goto help
|
||||
|
||||
if "%1" == "help" (
|
||||
:help
|
||||
echo.Please use `make ^<target^>` where ^<target^> is one of
|
||||
echo. html to make standalone HTML files
|
||||
echo. dirhtml to make HTML files named index.html in directories
|
||||
echo. singlehtml to make a single large HTML file
|
||||
echo. pickle to make pickle files
|
||||
echo. json to make JSON files
|
||||
echo. htmlhelp to make HTML files and a HTML help project
|
||||
echo. qthelp to make HTML files and a qthelp project
|
||||
echo. devhelp to make HTML files and a Devhelp project
|
||||
echo. epub to make an epub
|
||||
echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
|
||||
echo. text to make text files
|
||||
echo. man to make manual pages
|
||||
echo. texinfo to make Texinfo files
|
||||
echo. gettext to make PO message catalogs
|
||||
echo. changes to make an overview over all changed/added/deprecated items
|
||||
echo. xml to make Docutils-native XML files
|
||||
echo. pseudoxml to make pseudoxml-XML files for display purposes
|
||||
echo. linkcheck to check all external links for integrity
|
||||
echo. doctest to run all doctests embedded in the documentation if enabled
|
||||
echo. coverage to run coverage check of the documentation if enabled
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "clean" (
|
||||
for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
|
||||
del /q /s %BUILDDIR%\*
|
||||
goto end
|
||||
)
|
||||
|
||||
|
||||
REM Check if sphinx-build is available and fallback to Python version if any
|
||||
%SPHINXBUILD% 2> nul
|
||||
if errorlevel 9009 goto sphinx_python
|
||||
goto sphinx_ok
|
||||
|
||||
:sphinx_python
|
||||
|
||||
set SPHINXBUILD=python -m sphinx.__init__
|
||||
%SPHINXBUILD% 2> nul
|
||||
if errorlevel 9009 (
|
||||
echo.
|
||||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
|
||||
echo.installed, then set the SPHINXBUILD environment variable to point
|
||||
echo.to the full path of the 'sphinx-build' executable. Alternatively you
|
||||
echo.may add the Sphinx directory to PATH.
|
||||
echo.
|
||||
echo.If you don't have Sphinx installed, grab it from
|
||||
echo.http://sphinx-doc.org/
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
:sphinx_ok
|
||||
|
||||
|
||||
if "%1" == "html" (
|
||||
%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. The HTML pages are in %BUILDDIR%/html.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "dirhtml" (
|
||||
%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "singlehtml" (
|
||||
%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "pickle" (
|
||||
%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished; now you can process the pickle files.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "json" (
|
||||
%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished; now you can process the JSON files.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "htmlhelp" (
|
||||
%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished; now you can run HTML Help Workshop with the ^
|
||||
.hhp project file in %BUILDDIR%/htmlhelp.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "qthelp" (
|
||||
%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished; now you can run "qcollectiongenerator" with the ^
|
||||
.qhcp project file in %BUILDDIR%/qthelp, like this:
|
||||
echo.^> qcollectiongenerator %BUILDDIR%\qthelp\mozlint.qhcp
|
||||
echo.To view the help file:
|
||||
echo.^> assistant -collectionFile %BUILDDIR%\qthelp\mozlint.ghc
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "devhelp" (
|
||||
%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "epub" (
|
||||
%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. The epub file is in %BUILDDIR%/epub.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "latex" (
|
||||
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "latexpdf" (
|
||||
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
|
||||
cd %BUILDDIR%/latex
|
||||
make all-pdf
|
||||
cd %~dp0
|
||||
echo.
|
||||
echo.Build finished; the PDF files are in %BUILDDIR%/latex.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "latexpdfja" (
|
||||
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
|
||||
cd %BUILDDIR%/latex
|
||||
make all-pdf-ja
|
||||
cd %~dp0
|
||||
echo.
|
||||
echo.Build finished; the PDF files are in %BUILDDIR%/latex.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "text" (
|
||||
%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. The text files are in %BUILDDIR%/text.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "man" (
|
||||
%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. The manual pages are in %BUILDDIR%/man.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "texinfo" (
|
||||
%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "gettext" (
|
||||
%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "changes" (
|
||||
%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.The overview file is in %BUILDDIR%/changes.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "linkcheck" (
|
||||
%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Link check complete; look for any errors in the above output ^
|
||||
or in %BUILDDIR%/linkcheck/output.txt.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "doctest" (
|
||||
%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Testing of doctests in the sources finished, look at the ^
|
||||
results in %BUILDDIR%/doctest/output.txt.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "coverage" (
|
||||
%SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Testing of coverage in the sources finished, look at the ^
|
||||
results in %BUILDDIR%/coverage/python.txt.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "xml" (
|
||||
%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. The XML files are in %BUILDDIR%/xml.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "pseudoxml" (
|
||||
%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
|
||||
goto end
|
||||
)
|
||||
|
||||
:end
|
||||
25
tools/lint/docs/usage.rst
Normal file
25
tools/lint/docs/usage.rst
Normal file
@ -0,0 +1,25 @@
|
||||
Running Linters Locally
|
||||
=======================
|
||||
|
||||
You can run all the various linters in the tree using the ``mach lint`` command. Simply pass in the
|
||||
directory or file you wish to lint (defaults to current working directory):
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
./mach lint path/to/files
|
||||
|
||||
Multiple paths are allowed:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
./mach lint path/to/foo.js path/to/bar.py path/to/dir
|
||||
|
||||
``Mozlint`` will automatically determine which types of files exist, and which linters need to be run
|
||||
against them. For example, if the directory contains both JavaScript and Python files then mozlint
|
||||
will automatically run both ESLint and Flake8 against those files respectively.
|
||||
|
||||
To restrict which linters are invoked manually, pass in ``-l/--linter``:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
./mach lint -l eslint path/to/files
|
||||
91
tools/lint/mach_commands.py
Normal file
91
tools/lint/mach_commands.py
Normal file
@ -0,0 +1,91 @@
|
||||
# This Source Code Form is subject to the terms of the Mozilla Public
|
||||
# License, v. 2.0. If a copy of the MPL was not distributed with this
|
||||
# file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
||||
|
||||
from __future__ import absolute_import, print_function, unicode_literals
|
||||
|
||||
import argparse
|
||||
import os
|
||||
|
||||
from mozbuild.base import (
|
||||
MachCommandBase,
|
||||
)
|
||||
|
||||
|
||||
from mach.decorators import (
|
||||
CommandArgument,
|
||||
CommandProvider,
|
||||
Command,
|
||||
SubCommand,
|
||||
)
|
||||
|
||||
|
||||
here = os.path.abspath(os.path.dirname(__file__))
|
||||
|
||||
|
||||
@CommandProvider
|
||||
class MachCommands(MachCommandBase):
|
||||
|
||||
@Command(
|
||||
'lint', category='devenv',
|
||||
description='Run linters.')
|
||||
@CommandArgument(
|
||||
'paths', nargs='*', default=None,
|
||||
help="Paths to file or directories to lint, like "
|
||||
"'browser/components/loop' or 'mobile/android'. "
|
||||
"Defaults to the current directory if not given.")
|
||||
@CommandArgument(
|
||||
'-l', '--linter', dest='linters', default=None, action='append',
|
||||
help="Linters to run, e.g 'eslint'. By default all linters are run "
|
||||
"for all the appropriate files.")
|
||||
@CommandArgument(
|
||||
'-f', '--format', dest='fmt', default='stylish',
|
||||
help="Formatter to use. Defaults to 'stylish'.")
|
||||
def lint(self, paths, linters=None, fmt='stylish', **lintargs):
|
||||
"""Run linters."""
|
||||
from mozlint import LintRoller, formatters
|
||||
|
||||
paths = paths or ['.']
|
||||
|
||||
lint_files = self.find_linters(linters)
|
||||
|
||||
lintargs['exclude'] = 'obj*'
|
||||
lint = LintRoller(lintargs=lintargs)
|
||||
lint.read(lint_files)
|
||||
|
||||
# run all linters
|
||||
results = lint.roll(paths)
|
||||
|
||||
formatter = formatters.get(fmt)
|
||||
print(formatter(results))
|
||||
|
||||
@SubCommand('lint', 'setup',
|
||||
"Setup required libraries for specified lints.")
|
||||
@CommandArgument(
|
||||
'-l', '--linter', dest='linters', default=None, action='append',
|
||||
help="Linters to run, e.g 'eslint'. By default all linters are run "
|
||||
"for all the appropriate files.")
|
||||
def lint_setup(self, linters=None, **lintargs):
|
||||
from mozlint import LintRoller
|
||||
|
||||
lint_files = self.find_linters(linters)
|
||||
lint = LintRoller(lintargs=lintargs)
|
||||
lint.read(lint_files)
|
||||
|
||||
for l in lint.linters:
|
||||
if 'setup' in l:
|
||||
l['setup']()
|
||||
|
||||
def find_linters(self, linters=None):
|
||||
lints = []
|
||||
files = os.listdir(here)
|
||||
for f in files:
|
||||
name, ext = os.path.splitext(f)
|
||||
if ext != '.lint':
|
||||
continue
|
||||
|
||||
if linters and name not in linters:
|
||||
continue
|
||||
|
||||
lints.append(os.path.join(here, f))
|
||||
return lints
|
||||
7
tools/moz.build
Normal file
7
tools/moz.build
Normal file
@ -0,0 +1,7 @@
|
||||
# -*- Mode: python; c-basic-offset: 4; indent-tabs-mode: nil; tab-width: 40 -*-
|
||||
# vim: set filetype=python:
|
||||
# This Source Code Form is subject to the terms of the Mozilla Public
|
||||
# License, v. 2.0. If a copy of the MPL was not distributed with this
|
||||
# file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
||||
|
||||
SPHINX_TREES['lint'] = 'lint/docs'
|
||||
Loading…
Reference in New Issue
Block a user