<commit_before>Contributing and feedback guidelines
####################################

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 <https://github.com/getpelican/pelican/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.

.. include:: ../CONTRIBUTING.rst

Setting up the development environment
======================================

While there are many ways to set up one's development environment, following
is a method that uses `virtualenv <http://www.virtualenv.org/>`_. 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 .

Building the docs
=================

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.

Running the test suite
======================

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/

Testing on Python 2 and 3
-------------------------

Testing on Python 3 currently requires some extra steps: installing
Python 3-compatible versions of dependent packages and plugins.

Tox_ is a useful tool to run tests on both versions. It will install the
Python 3-compatible version of dependent packages.

.. _Tox: http://testrun.org/tox/latest/

Python 3 development tips
=========================<commit_msg>English and French locales must be installed<commit_after>Contributing and feedback guidelines
####################################

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 <https://github.com/getpelican/pelican/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.

.. include:: ../CONTRIBUTING.rst

Setting up the development environment
======================================

While there are many ways to set up one's development environment, following
is a method that uses `virtualenv <http://www.virtualenv.org/>`_. 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 .

Building the docs
=================

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.

Running the test suite
======================

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, **make sure you have both ``en_EN.utf8`` and
``fr_FR.utf8`` locales installed**, and then run 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/

Testing on Python 2 and 3
-------------------------

Testing on Python 3 currently requires some extra steps: installing
Python 3-compatible versions of dependent packages and plugins.

Tox_ is a useful tool to run tests on both versions. It will install the
Python 3-compatible version of dependent packages.

.. _Tox: http://testrun.org/tox/latest/

Python 3 development tips
=========================
{'fraction_non_alphanumeric': 0.11042493750918983, 'fraction_numerical': 0.002940744008234083, 'mean_word_length': 3.86204431736955, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 4, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1414045', 'n_tokens_mistral': 1812, 'n_tokens_neox': 1709, 'n_words': 846}