There are many ways to contribute to Pelican. You can improve the documentation, add missing features, and fix bugs (or just report them). You can also help out by reviewing and commenting on existing issues.
Don’t hesitate to fork Pelican and submit an issue or pull request on GitHub. When doing so, please adhere to the following guidelines.
Before you ask for help, please make sure you do the following:
NOTE: The most common sources of problems are anomalies in (1) themes, (2) settings files, and (3) make/fab automation wrappers. If you can’t reproduce your problem when using the following steps to generate your site, then the problem is almost certainly with your chosen theme and/or settings file (and not Pelican itself):
cd ~/projects/your-site
git clone https://github.com/getpelican/pelican ~/projects/pelican
pelican content -s ~/projects/pelican/samples/pelican.conf.py -t ~/projects/pelican/pelican/themes/notmyidea
If despite the above efforts you still cannot resolve your problem, be sure to include in your inquiry the following information, preferably in the form of links to content uploaded to a paste service, GitHub repository, or other publicly-accessible location:
Once the above preparation is ready, you can contact people willing to help via (preferably) the #pelican IRC channel or send a message to authors at getpelican dot com. Remember to include all the information you prepared.
Before you submit a contribution, please ask whether it is desired so that you don’t spend a lot of time working on something that would be rejected for a known reason. Consider also whether your new feature might be better suited as a plugin — you can ask for help to make that determination.
Check out our Git Tips page or ask for help if you need assistance or have any questions about these guidelines.
While there are many ways to set up one’s development environment, following is a method that uses virtualenv. If you don’t have virtualenv installed, you can install it via:
$ pip install virtualenv
Virtual environments allow you to work on Python projects which are isolated from one another so you can use different packages (and package versions) with different projects.
To create and activate a virtual environment, use the following syntax:
$ virtualenv ~/virtualenvs/pelican
$ cd ~/virtualenvs/pelican
$ . bin/activate
To clone the Pelican source:
$ git clone https://github.com/getpelican/pelican.git src/pelican
To install the development dependencies:
$ cd src/pelican
$ pip install -r dev_requirements.txt
To install Pelican and its dependencies:
$ python setup.py develop
Or using pip:
$ pip install -e .
If you make changes to the documentation, you should preview your changes before committing them:
$ pip install sphinx
$ cd src/pelican/docs
$ make html
Open _build/html/index.html in your browser to preview the documentation.
Each time you add a feature, there are two things to do regarding tests: check that the existing tests pass, and add tests for the new feature or bugfix.
The tests live in pelican/tests and you can run them using the “discover” feature of unittest:
$ python -m unittest discover
After making your changes and running the tests, you may see a test failure mentioning that “some generated files differ from the expected functional tests output.” If you have made changes that affect the HTML output generated by Pelican, and the changes to that output are expected and deemed correct given the nature of your changes, then you should update the output used by the functional tests. To do so, you can use the following two commands:
$ LC_ALL=en_US.utf8 pelican -o pelican/tests/output/custom/ \
-s samples/pelican.conf.py samples/content/
$ LC_ALL=fr_FR.utf8 pelican -o pelican/tests/output/custom_locale/ \
-s samples/pelican.conf_FR.py samples/content/
$ LC_ALL=en_US.utf8 pelican -o pelican/tests/output/basic/ \
samples/content/
Here are some tips that may be useful when doing some code for both Python 2.7 and Python 3 at the same time:
Try to use logging with appropriate levels.
For logging messages that are not repeated, use the usual Python way:
# at top of file
import logging
logger = logging.getLogger(__name__)
# when needed
logger.warning("A warning with %s formatting", arg_to_be_formatted)
Do not format log messages yourself. Use %s formatting in messages and pass arguments to logger. This is important, because Pelican logger will preprocess some arguments (like Exceptions) for Py2/Py3 compatibility.
If the log message can occur several times, you may want to limit the log to prevent flooding. In order to do that, use the extra keyword argument for the logging message in the following format:
logger.warning("A warning with %s formatting", arg_to_be_formatted,
extra={'limit_msg': 'A generic message for too many warnings'})
Optionally, you can also set 'limit_args' as a tuple of arguments in extra dict if your generic message needs formatting.
Limit is set to 5, i.e, first four logs with the same 'limit_msg' are outputted normally but the fifth one will be logged using 'limit_msg' (and 'limit_args' if present). After the fifth, corresponding log messages will be ignored.
For example, if you want to log missing resources, use the following code:
for resource in resources:
if resource.is_missing:
logger.warning(
'The resource %s is missing', resource.name,
extra={'limit_msg': 'Other resources were missing'})
The log messages will be displayed as follows:
WARNING: The resource prettiest_cat.jpg is missing
WARNING: The resource best_cat_ever.jpg is missing
WARNING: The resource cutest_cat.jpg is missing
WARNING: The resource lolcat.jpg is missing
WARNING: Other resources were missing
If you’re logging inside an except block, you may want to provide the traceback information as well. You can do that by setting exc_info keyword argument to True during logging. However, doing so by default can be undesired because tracebacks are long and can be confusing to regular users. Try to limit them to --debug mode like the following:
try:
some_action()
except Exception as e:
logger.error('Exception occurred: %s', e,
exc_info=settings.get('DEBUG', False))