3b75d900f6
* Added: Sphinx configuration including readthedocs config * Added: Sphinx fabric task to auto-document the project * Fixed: Some issues in the code causing autodoc to fail when parsing * Added: Manual docs - structure, proof of concepts and RsT examples * Fixed: RsT formatting in docstrings * Fixed: Some adjacent minor style and lint issues
297 lines
10 KiB
Python
297 lines
10 KiB
Python
# pylint: disable=not-context-manager
|
|
"""
|
|
Fabric tasks for PyBitmessage devops operations.
|
|
|
|
Note that where tasks declare params to be bools, they use coerce_bool() and so will accept any commandline (string)
|
|
representation of true or false that coerce_bool() understands.
|
|
|
|
"""
|
|
|
|
import os
|
|
import sys
|
|
|
|
from fabric.api import run, task, hide, cd, settings, sudo
|
|
from fabric.contrib.project import rsync_project
|
|
from fabvenv import virtualenv
|
|
|
|
from fabfile.lib import (
|
|
autopep8, PROJECT_ROOT, VENV_ROOT, coerce_bool, flatten,
|
|
get_filtered_pycodestyle_output, get_filtered_flake8_output, get_filtered_pylint_output,
|
|
)
|
|
|
|
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(os.path.dirname(__file__)), 'src'))) # noqa:E402
|
|
from version import softwareVersion # pylint: disable=wrong-import-position
|
|
|
|
|
|
def get_tool_results(file_list):
|
|
"""Take a list of files and resuln the results of applying the tools"""
|
|
|
|
results = []
|
|
for path_to_file in file_list:
|
|
result = {}
|
|
result['pycodestyle_violations'] = get_filtered_pycodestyle_output(path_to_file)
|
|
result['flake8_violations'] = get_filtered_flake8_output(path_to_file)
|
|
result['pylint_violations'] = get_filtered_pylint_output(path_to_file)
|
|
result['path_to_file'] = path_to_file
|
|
result['total_violations'] = sum([
|
|
len(result['pycodestyle_violations']),
|
|
len(result['flake8_violations']),
|
|
len(result['pylint_violations']),
|
|
])
|
|
results.append(result)
|
|
return results
|
|
|
|
|
|
def print_results(results, top, verbose, details):
|
|
"""Print an item with the appropriate verbosity / detail"""
|
|
|
|
if verbose:
|
|
print ''.join(
|
|
[
|
|
os.linesep,
|
|
'total pycodestyle flake8 pylint path_to_file',
|
|
os.linesep,
|
|
]
|
|
)
|
|
|
|
for item in sort_and_slice(results, top):
|
|
|
|
if verbose:
|
|
line = "{0} {1} {2} {3} {4}".format(
|
|
item['total_violations'],
|
|
len(item['pycodestyle_violations']),
|
|
len(item['flake8_violations']),
|
|
len(item['pylint_violations']),
|
|
item['path_to_file'],
|
|
)
|
|
else:
|
|
line = item['path_to_file']
|
|
print line
|
|
|
|
if details:
|
|
print "pycodestyle:"
|
|
for detail in flatten(item['pycodestyle_violations']):
|
|
print detail
|
|
print
|
|
|
|
print "flake8:"
|
|
for detail in flatten(item['flake8_violations']):
|
|
print detail
|
|
print
|
|
|
|
print "pylint:"
|
|
for detail in flatten(item['pylint_violations']):
|
|
print detail
|
|
print
|
|
|
|
|
|
def sort_and_slice(results, top):
|
|
"""Sort dictionary items by the `total_violations` key and honour top"""
|
|
|
|
returnables = []
|
|
for item in sorted(
|
|
results,
|
|
reverse=True,
|
|
key=lambda x: x['total_violations']
|
|
)[:top]:
|
|
returnables.append(item)
|
|
return returnables
|
|
|
|
|
|
def generate_file_list(filename):
|
|
"""Return an unfiltered list of absolute paths to the files to act on"""
|
|
|
|
with hide('warnings', 'running', 'stdout'):
|
|
with virtualenv(VENV_ROOT):
|
|
|
|
if filename:
|
|
filename = os.path.abspath(filename)
|
|
if not os.path.exists(filename):
|
|
print "Bad filename, specify a Python file"
|
|
sys.exit(1)
|
|
else:
|
|
file_list = [filename]
|
|
|
|
else:
|
|
with cd(PROJECT_ROOT):
|
|
file_list = [
|
|
os.path.abspath(i.rstrip('\r'))
|
|
for i in run('find . -name "*.py"').split(os.linesep)
|
|
]
|
|
|
|
return file_list
|
|
|
|
|
|
def create_dependency_graphs():
|
|
"""
|
|
To better understand the relationship between methods, dependency graphs can be drawn between functions and
|
|
methods.
|
|
|
|
Since the resulting images are large and could be out of date on the next commit, storing them in the repo is
|
|
pointless. Instead, it makes sense to build a dependency graph for a particular, documented version of the code.
|
|
|
|
.. todo:: Consider saving a hash of the intermediate dotty file so unnecessary image generation can be avoided.
|
|
|
|
"""
|
|
with virtualenv(VENV_ROOT):
|
|
with hide('running', 'stdout'):
|
|
|
|
# .. todo:: consider a better place to put this, use a particular commit
|
|
with cd(PROJECT_ROOT):
|
|
with settings(warn_only=True):
|
|
if run('stat pyan').return_code:
|
|
run('git clone https://github.com/davidfraser/pyan.git')
|
|
with cd(os.path.join(PROJECT_ROOT, 'pyan')):
|
|
run('git checkout pre-python3')
|
|
|
|
# .. todo:: Use better settings. This is MVP to make a diagram
|
|
with cd(PROJECT_ROOT):
|
|
file_list = run("find . -type f -name '*.py' ! -path './src/.eggs/*'").split('\r\n')
|
|
for cmd in [
|
|
'neato -Goverlap=false -Tpng > deps-neato.png',
|
|
'sfdp -Goverlap=false -Tpng > deps-sfdp.png',
|
|
'dot -Goverlap=false -Tpng > deps-dot.png',
|
|
]:
|
|
pyan_cmd = './pyan/pyan.py {} --dot'.format(' '.join(file_list))
|
|
sed_cmd = r"sed s'/http\-old/http_old/'g" # dot doesn't like dashes
|
|
run('|'.join([pyan_cmd, sed_cmd, cmd]))
|
|
|
|
run('mv *.png docs/_build/html/_static/')
|
|
|
|
|
|
@task
|
|
def code_quality(verbose=True, details=False, fix=False, filename=None, top=10):
|
|
"""
|
|
Check code quality.
|
|
|
|
By default this command will analyse each Python file in the project with a variety of tools and display the count
|
|
or details of the violations discovered, sorted by most violations first.
|
|
|
|
Default usage:
|
|
|
|
$ fab -H localhost code_quality
|
|
|
|
:param top: Display / fix only the top N violating files, a value of 0 will display / fix all files
|
|
:type top: int, default 10
|
|
:param verbose: Display a header and the counts, without this you just get the filenames in order
|
|
:type verbose: bool, default True
|
|
:param details: Display the violations one per line after the count / file summary
|
|
:type details: bool, default False
|
|
:param fix: Run autopep8 aggressively on the displayed file(s)
|
|
:type fix: bool, default False
|
|
:param filename: Don't test/fix the top N, just the specified file
|
|
:type filename: string, valid path to a file, default all files in the project
|
|
:return: None, exit status equals total number of violations
|
|
:rtype: None
|
|
|
|
Intended to be temporary until we have improved code quality and have safeguards to maintain it in place.
|
|
|
|
"""
|
|
|
|
verbose = coerce_bool(verbose)
|
|
details = coerce_bool(details)
|
|
fix = coerce_bool(fix)
|
|
top = int(top) or -1
|
|
|
|
file_list = generate_file_list(filename)
|
|
results = get_tool_results(file_list)
|
|
|
|
if fix:
|
|
for item in sort_and_slice(results, top):
|
|
autopep8(item['path_to_file'])
|
|
# Recalculate results after autopep8 to surprise the user the least
|
|
results = get_tool_results(file_list)
|
|
|
|
print_results(results, top, verbose, details)
|
|
sys.exit(sum([item['total_violations'] for item in results]))
|
|
|
|
|
|
@task
|
|
def build_docs(dep_graph=False, apidoc=True):
|
|
"""
|
|
Build the documentation locally.
|
|
|
|
:param dep_graph: Build the dependency graphs
|
|
:type dep_graph: Bool, default False
|
|
:param apidoc: Build the automatically generated rst files from the source code
|
|
:type apidoc: Bool, default True
|
|
|
|
Default usage:
|
|
|
|
$ fab -H localhost build_docs
|
|
|
|
Implementation:
|
|
|
|
First, a dependency graph is generated and converted into an image that is referenced in the development page.
|
|
|
|
Next, the sphinx-apidoc command is (usually) run which searches the code. As part of this it loads the modules and
|
|
if this has side-effects then they will be evident. Any documentation strings that make use of Python documentation
|
|
conventions (like parameter specification) or the Restructured Text (RsT) syntax will be extracted.
|
|
|
|
Next, the `make html` command is run to generate HTML output. Other formats (epub, pdf) are available.
|
|
|
|
.. todo:: support other languages
|
|
|
|
"""
|
|
|
|
apidoc = coerce_bool(apidoc)
|
|
|
|
if coerce_bool(dep_graph):
|
|
create_dependency_graphs()
|
|
|
|
with virtualenv(VENV_ROOT):
|
|
with hide('running'):
|
|
|
|
apidoc_result = 0
|
|
if apidoc:
|
|
run('mkdir -p {}'.format(os.path.join(PROJECT_ROOT, 'docs', 'autodoc')))
|
|
with cd(os.path.join(PROJECT_ROOT, 'docs', 'autodoc')):
|
|
with settings(warn_only=True):
|
|
run('rm *.rst')
|
|
with cd(os.path.join(PROJECT_ROOT, 'docs')):
|
|
apidoc_result = run('sphinx-apidoc -o autodoc ..').return_code
|
|
|
|
with cd(os.path.join(PROJECT_ROOT, 'docs')):
|
|
make_result = run('make html').return_code
|
|
return_code = apidoc_result + make_result
|
|
|
|
sys.exit(return_code)
|
|
|
|
|
|
@task
|
|
def push_docs(path=None):
|
|
"""
|
|
Upload the generated docs to a public server.
|
|
|
|
Default usage:
|
|
|
|
$ fab -H localhost push_docs
|
|
|
|
.. todo:: support other languages
|
|
.. todo:: integrate with configuration management data to get web root and webserver restart command
|
|
|
|
"""
|
|
|
|
# Making assumptions
|
|
WEB_ROOT = path if path is not None else os.path.join('var', 'www', 'html', 'pybitmessage', 'en', 'latest')
|
|
VERSION_ROOT = os.path.join(os.path.dirname(WEB_ROOT), softwareVersion)
|
|
|
|
rsync_project(
|
|
remote_dir=VERSION_ROOT,
|
|
local_dir=os.path.join(PROJECT_ROOT, 'docs', '_build', 'html')
|
|
)
|
|
result = run('ln -sf {0} {1}'.format(WEB_ROOT, VERSION_ROOT))
|
|
if result.return_code:
|
|
print 'Linking the new release failed'
|
|
|
|
# More assumptions
|
|
sudo('systemctl restart apache2')
|
|
|
|
|
|
@task
|
|
def clean():
|
|
"""Clean up files generated by fabric commands."""
|
|
with hide('running', 'stdout'):
|
|
with cd(PROJECT_ROOT):
|
|
run(r"find . -name '*.pyc' -exec rm '{}' \;")
|