atelier.fablib¶
(This module’s source code is available here.)
A library for fabric with tasks I use to manage my Python projects.
fab commands¶
Documenting¶
- fab blog¶
Edit today’s blog entry, create an empty file if it doesn’t yet exist.
- fab bd¶
Build docs. Build Sphinx HTML docs for this project.
This run fab readme, followed by sphinx build html in every directory defined in env.doc_trees.
- fab pd¶
Publish docs. Upload docs to public web server.
- fab clean¶
Remove temporary and generated files:
- Sphinx .build files
- Dangling .pyc files which don’t have a corresponding .py file.
- cache directories of demo projects
- fab readme¶
Generate or update README.txt or README.rst file from SETUP_INFO.
- fab api¶
No longer exists because we now use autosummary instead of sphinx-apidoc.
Generate .rst files below docs/api by running sphinx-apidoc.
This is no longer used by most of my projects, at least those which I converted to sphinx.ext.autosummary.
Internationalization¶
- fab mm¶
(“make messages”)
Extracts messages from both code and userdocs, then initializes and updates all catalogs.
Deploy¶
- fab ci¶
Checkin and push to repository, using today’s blog entry as commit message.
- fab release¶
Write a source distribution archive to your env.sdist_dir, then upload it to PyPI. Create a version tag if env.revision_control_system is 'git'.
This command will fail if this project has previously been released with the same version.
- fab reg¶
Register this project (and its current version) to PyPI.
- fab sdist¶
Write a source distribution archive to your env.sdist_dir.
Testing¶
- fab initdb¶
Run initdb_demo on every env.demo_projects.
- fab test¶
Run the test suite of this project.
- fab test_sdist¶
Creates a temporay virtualenv, installs your project and runs your test suite.
- creates and activates a temporay virtualenv,
- calls pip install --extra-index <env.sdist_dir> <prjname>
- runs python setup.py test
- removes temporary files.
Assumes that you previously did fab sdist of all your projects related to this project.
When using this, you should configure a local download cache for pip, e.g. with something like this in your ~/.pip/pip.conf:
[global] download-cache=/home/luc/.pip/cache
Installation¶
To be used by creating a fabfile.py in your project’s root directory with at least the following two lines:
from atelier.fablib import *
setup_from_fabfile(flobals())
See setup_from_fabfile() for more information.
Configuration files¶
- fabfile.py¶
In your fabfile.py file you can specify project-specific configuration settings. Example content:
from atelier.fablib import *
setup_from_fabfile(globals(), "foobar")
env.languages = "de fr et nl".split()
env.tolerate_sphinx_warnings = True
add_demo_project('foobar/demo')
- .fabricrc¶
To specify certain default preferences for all your projects, you can create a file named .fabricrc in your home directory with content like this:
user = luc
blogger_project = lino
docs_rsync_dest = luc@example.org:~/public_html/%s
sdist_dir = /home/luc/projects/lino/docs/dl
temp_dir = /home/luc/tmp
Project settings¶
fabric works with a global “environment” object named env.
The following section documents the possible attributes of this object as used by atelier.fablib.
You usually define these in your fabfile.py. For some of them (those who are simple strings) you can define user-specific default values in a .fabricrc file.
- class atelier.fablib.env¶
- sdist_dir¶
- editor_command¶
A string with the command name of a non waiting editor.
editor_command = “emacsclient -n {0}”
- docs_rsync_dest¶
A Python template string which defines the rsync destination for publishing your projects documentation. Used by fab pub.
Example:
env.docs_rsync_dest = 'luc@example.org:~/public_html/%s'
The %s in this template will be replaced by a name xxx_yyy, where xxx is the internal name of this project and yyy the name of the doctree (taken from doc_trees).
- doc_trees¶
A list of directory names (relative to your project directory) containing Sphinx document trees. Default value is ['docs']
If this project has a main package, then env.doc_trees will be replaced by doc_trees attribute of that module.
- tolerate_sphinx_warnings¶
Whether sphinx-build html should tolerate warnings.
- languages¶
A list of language codes for which userdocs are being maintained.
- apidoc_exclude_pathnames¶
No longer used because we now use autosummary instead of sphinx-apidoc.
a list of filenames (or directory names) to be excluded when you run fab api.
- revision_control_system¶
The revision control system used by your project. Allowed values are ‘git’, ‘hg’ or None. Used by fab ci.
- use_mercurial¶
No longer used. Use env.revision_control_system instead.)
- demo_projects¶
The list of Django demo projects included in this project.
Django demo projects are used by the test suite and the Sphinx documentation. Before running fab test or fab bd, they must have been initialized. To initialize them, run fab initdb.
It is not launched automatically by fab test or fab bd because it can take some time and is not always necessary.
History¶
- 20141020 moved doc_trees project to atelier.Project.
- 20141001 added support for multiple doc trees per project (env.doc_trees).
- 20140116 : added support for managing namespace packages
TODO¶
- replace env.blogger_project by an attribute of the main module (like intersphinx_urls)
(The rest of this page is automatically generated stuff.)
Functions
| abort(msg) | Abort execution, print msg to stderr and exit with error status (1.) |
| add_demo_project(p) | Register the specified settings module as being a Django demo project. |
| clean_demo_caches() | Remove the cache directory of every demo project (see env.demo_projects). |
| cleanup_pyc(p) | Thanks to oddthinking on http://stackoverflow.com/questions/2528283 |
| confirm(question[, default]) | Ask user a yes/no question and return their response as True or False. |
| extract_messages() | Extract messages from source files to django.pot file |
| extract_messages_userdocs() | Run the Sphinx gettext builder on userdocs. |
| format_date([date, format, locale]) | Return a date formatted according to the given pattern. |
| get_blog_entry(today) | Return an RstFile object representing the blog entry for that date in the current project. |
| get_current_date() | Useful when a working day lasted longer than midnight, or when you start some work in the evening, knowing that you won’t commit it before the next morning. |
| get_doc_trees() | |
| get_locale_dir() | |
| i2d(i) | Convert int to date. |
| init_catalog_code() | Create code .po files if necessary. |
| lcd(path) | Context manager for updating local current working directory. |
| local(command[, capture, shell]) | Run a command on the local system. |
| must_confirm(*args, **kw) | |
| must_exist(p) | |
| publish_docs(build_dir, dest_url) | |
| puts(text[, show_prefix, end, flush]) | An alias for print whose output is managed by Fabric’s output controls. |
| py_clean() | Delete dangling .pyc files. |
| rmtree_after_confirm(p) | |
| run_in_demo_projects(admin_cmd, *more) | Run the given shell command in each demo project (see env.demo_projects). |
| setup_babel_userdocs(babelcmd) | Create userdocs .po files if necessary. |
| setup_from_fabfile(globals_dict[, ...]) | To be called from within your project’s fabfile.py. |
| setup_from_project(globals_dict[, ...]) | To be called from within your project’s fabfile.py. |
| show_pypi_status() | |
| show_revision_status() | |
| sphinx_build(builder, docs_dir[, ...]) | |
| sphinx_clean() | Delete all generated Sphinx files. |
| sync_docs_data(docs_dir) | |
| task(*args, **kwargs) | Decorator declaring the wrapped function to be a new-style task. |
| unused_build_api(*cmdline_args) | Generate .rst files in docs/api. |
| update_catalog_code() | Update .po files from .pot file. |
Classes
| Path | |
| RstFile(local_root, url_root, parts) |
Exceptions
| MissingConfig(name) |
- atelier.fablib.add_demo_project(p)¶
Register the specified settings module as being a Django demo project. See also env.demo_projects.
- atelier.fablib.build_userdocs¶
Deprecated. sphinx-build the userdocs tree in all languages
- atelier.fablib.clean_demo_caches()¶
Remove the cache directory of every demo project (see env.demo_projects).
- atelier.fablib.cleanup_pyc(p)¶
Thanks to oddthinking on http://stackoverflow.com/questions/2528283
- atelier.fablib.compile_catalog¶
Compile .po files to .mo files.
- atelier.fablib.double_dump_test¶
Perform a “double dump test” on every demo database. TODO: convert this to a Lino management command.
- atelier.fablib.edit_blog_entry¶
Edit today’s blog entry, create an empty file if it doesn’t yet exist.
- atelier.fablib.extract_messages()¶
Extract messages from source files to django.pot file
- atelier.fablib.extract_messages_userdocs()¶
Run the Sphinx gettext builder on userdocs.
- atelier.fablib.get_blog_entry(today)¶
Return an RstFile object representing the blog entry for that date in the current project.
- atelier.fablib.get_current_date()¶
Useful when a working day lasted longer than midnight, or when you start some work in the evening, knowing that you won’t commit it before the next morning.
Note that you must specify the date using the YYYYMMDD format.
- atelier.fablib.init_catalog_code()¶
Create code .po files if necessary.
- atelier.fablib.make_messages¶
Extract messages, then initialize and update all catalogs.
- atelier.fablib.makescreenshots¶
generate screenshot .jpg files to gen/screenshots.
- atelier.fablib.py_clean()¶
Delete dangling .pyc files.
- atelier.fablib.pypi_release¶
See fab release.
- atelier.fablib.run_in_demo_projects(admin_cmd, *more)¶
Run the given shell command in each demo project (see env.demo_projects).
- atelier.fablib.run_tests_coverage¶
Run all tests, creating coverage report
- atelier.fablib.setup_babel_userdocs(babelcmd)¶
Create userdocs .po files if necessary.
- atelier.fablib.setup_from_fabfile(globals_dict, main_package=None, settings_module_name=None)¶
To be called from within your project’s fabfile.py.
Minimal example:
from atelier.fablib import * setup_from_fabfile(globals())
If this doctree is the main doctree of a Python project, then the minimal example should be:
from atelier.fablib import * setup_from_fabfile(globals(), "foobar")
Where “foobar” is the Python name of your project’s main package.
- atelier.fablib.setup_from_project(globals_dict, main_package=None, settings_module_name=None)¶
To be called from within your project’s fabfile.py.
Minimal example:
from atelier.fablib import * setup_from_fabfile(globals())
If this doctree is the main doctree of a Python project, then the minimal example should be:
from atelier.fablib import * setup_from_fabfile(globals(), "foobar")
Where “foobar” is the Python name of your project’s main package.
- atelier.fablib.sphinx_build_linkcheck¶
sphinxbuild -b linkcheck docs.
- atelier.fablib.sphinx_clean()¶
Delete all generated Sphinx files.
- atelier.fablib.summary¶
Print a summary to stdout.
- atelier.fablib.syncscreenshots¶
synchronize gen/screenshots to userdocs/gen/screenshots.
- atelier.fablib.unused_run_sphinx_doctest¶
Run Sphinx doctest tests. Not maintained because i cannot prevent it from also trying to test the documents in django_doctests which must be tested separately.
- atelier.fablib.update_catalog_code()¶
Update .po files from .pot file.
- atelier.fablib.write_readme¶
See fab readme.