Merge branch 'master' into hidden-posts

docs/changelog.rst

@@ -1,6 +1,52 @@
 Release history
 ###############
 
+4.6.0 - 2021-03-23
+==================
+
+* Add new URL pattern to ``PAGINATION_PATTERNS`` for the last page in the list `(#1401) <https://github.com/getpelican/pelican/issues/1401>`_
+* Speed up ``livereload`` Invoke task via caching `(#2847) <https://github.com/getpelican/pelican/pull/2847>`_
+* Ignore ``None`` return value from ``get_generators`` signal `(#2850) <https://github.com/getpelican/pelican/pull/2850>`_
+* Relax dependency minimum versions and remove upper bounds
+
+4.5.4 - 2021-01-04
+==================
+
+Replace plugin definitions in settings with string representations after registering, so they can be cached correctly `(#2828) <https://github.com/getpelican/pelican/issues/2828>`_.
+
+4.5.3 - 2020-12-01
+==================
+
+Fix a mistake made in PR #2821
+
+4.5.2 - 2020-11-22
+==================
+
+Improve logging of generators and writer loaders
+
+4.5.1 - 2020-11-02
+==================
+
+* Refactor intra-site link discovery in order to match more permissively `(#2646) <https://github.com/getpelican/pelican/issues/2646>`_
+* Fix plugins running twice in auto-reload mode `(#2817) <https://github.com/getpelican/pelican/issues/2817>`_
+* Add notice to use ``from pelican import signals`` instead of ``import pelican.signals`` `(#2805) <https://github.com/getpelican/pelican/issues/2805>`_
+
+4.5.0 - 2020-08-20
+==================
+
+* Add namespace plugin support; list plugins via ``pelican-plugins`` command
+* Override settings via ``-e`` / ``--extra-settings`` CLI option flags
+* Add settings for custom Jinja globals and tests
+* Customize article summary ellipsis via ``SUMMARY_END_SUFFIX`` setting
+* Customize Typogrify dash handling via new ``TYPOGRIFY_DASHES`` setting
+* Support Unicode when generating slugs
+* Support Asciidoc ``.adoc`` file generation in Pelican importer
+* Improve user experience when ``pelican --listen`` web server is quit
+* Improve Invoke tasks template
+* Include tests in source distributions
+* Switch CI from Travis to GitHub Actions
+* Remove support for Python 2.7
+
 4.2.0 - 2019-10-17
 ==================
 
@@ -12,7 +58,7 @@ Release history
 4.1.3 - 2019-10-09
 ==================
 
-* Fix quick-start docs regarding `pelican --listen`
+* Fix quick-start docs regarding ``pelican --listen``
 * Set default listen address to 127.0.0.1
 * Add extra/optional Markdown dependency to setup.py
 * Use correct SSH port syntax for rsync in tasks.py
@@ -30,8 +76,8 @@ Fix pelican.settings.load_source to avoid caching issues - PR #2621
 
 * Add AutoPub to auto-publish releases on PR merge
 * Add CSS classes for reStructuredText figures
-* Pass `argv` to Pelican `main` entrypoint
-* Set default content status to a blank string rather than `None`
+* Pass ``argv`` to Pelican ``main`` entrypoint
+* Set default content status to a blank string rather than ``None``
 
 4.1.0 - 2019-07-14
 ==================

docs/contribute.rst

@@ -44,9 +44,9 @@ to manually create and activate a virtual environment::
 
 Install the needed dependencies and set up the project::
 
-    pip install invoke
+    python -m pip install invoke
     invoke setup
-    pip install -e ~/projects/pelican
+    python -m pip install -e ~/projects/pelican
 
 Your local environment should now be ready to go!
 
@@ -75,11 +75,14 @@ via::
 
     invoke tests
 
-In addition to running the test suite, the above invocation will also check code
-style and let you know whether non-conforming patterns were found. In some cases
-these linters will make the needed changes directly, while in other cases you
-may need to make additional changes until ``invoke tests`` no longer reports any
-code style violations.
+In addition to running the test suite, it is important to also ensure that any
+lines you changed conform to code style guidelines. You can check that via::
+
+    invoke lint
+
+If code style violations are found in lines you changed, correct those lines
+and re-run the above lint command until they have all been fixed. You do not
+need to address style violations, if any, for code lines you did not touch.
 
 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
@@ -145,9 +148,20 @@ Create a topic branch for your plugin bug fix or feature::
 
     git checkout -b name-of-your-bugfix-or-feature
 
-After writing new tests for your plugin changes, run the plugin test suite::
+After writing new tests for your plugin changes, run the plugin test suite and
+check for code style compliance via::
 
     invoke tests
+    invoke lint
+
+If style violations are found, many of them can be addressed automatically via::
+
+    invoke black
+    invoke isort
+
+If style violations are found even after running the above auto-formatters,
+you will need to make additional manual changes until ``invoke lint`` no longer
+reports any code style violations.
 
 .. _plugin template: https://github.com/getpelican/cookiecutter-pelican-plugin
 .. _Simple Footnotes: https://github.com/pelican-plugins/simple-footnotes

docs/faq.rst

@@ -74,7 +74,7 @@ Markdown format, you will need to explicitly install the Markdown library. You
 can do so by typing the following command, prepending ``sudo`` if permissions
 require it::
 
-    pip install markdown
+    python -m pip install markdown
 
 Can I use arbitrary metadata in my templates?
 =============================================
@@ -174,28 +174,18 @@ your site.
 Feeds are still generated when this warning is displayed, but links within may
 be malformed and thus the feed may not validate.
 
-My feeds are broken since I upgraded to Pelican 3.x
-===================================================
+Can I force Atom feeds to show only summaries instead of article content?
+=========================================================================
 
-Starting in 3.0, some of the FEED setting names were changed to more explicitly
-refer to the Atom feeds they inherently represent (much like the FEED_RSS
-setting names). Here is an exact list of the renamed settings::
-
-    FEED -> FEED_ATOM
-    TAG_FEED -> TAG_FEED_ATOM
-    CATEGORY_FEED -> CATEGORY_FEED_ATOM
-
-Starting in 3.1, the new feed ``FEED_ALL_ATOM`` has been introduced: this feed
-will aggregate all posts regardless of their language. This setting generates
-``'feeds/all.atom.xml'`` by default and ``FEED_ATOM`` now defaults to ``None``.
-The following feed setting has also been renamed::
-
-    TRANSLATION_FEED -> TRANSLATION_FEED_ATOM
-
-Older themes that referenced the old setting names may not link properly. In
-order to rectify this, please update your theme for compatibility by changing
-the relevant values in your template files. For an example of complete feed
-headers and usage please check out the ``simple`` theme.
+Instead of having to open a separate browser window to read articles, the
+overwhelming majority of folks who use feed readers prefer to read content
+within the feed reader itself. Mainly for that reason, Pelican does not support
+restricting Atom feeds to only contain summaries. Unlike Atom feeds, the RSS
+feed specification does not include a separate ``content`` field, so by default
+Pelican publishes RSS feeds that only contain summaries (but can optionally be
+set to instead publish full content RSS feeds). So the default feed generation
+behavior provides users with a choice: subscribe to Atom feeds for full content
+or to RSS feeds for just the summaries.
 
 Is Pelican only suitable for blogs?
 ===================================
@@ -228,7 +218,7 @@ which will make it compare the file checksums in a much faster way than Pelican
 would.
 
 When only several specific output files are of interest (e.g. when working on
-some specific page or the theme templates), the `WRITE_SELECTED` option may
+some specific page or the theme templates), the ``WRITE_SELECTED`` option may
 help, see :ref:`writing_only_selected_content`.
 
 How to process only a subset of all articles?
@@ -242,11 +232,10 @@ command similar to ``cd content; find -name '*.md' | head -n 10``.
 My tag-cloud is missing/broken since I upgraded Pelican
 =======================================================
 
-In an ongoing effort to steamline Pelican, `tag_cloud` generation has been
-moved out of the pelican core and into a separate `plugin
-<https://github.com/getpelican/pelican-plugins/tree/master/tag_cloud>`_. See
-the :ref:`plugins` documentation further information about the Pelican plugin
-system.
+In an ongoing effort to streamline Pelican, tag cloud generation has been
+moved out of Pelican core and into a separate `plugin
+<https://github.com/pelican-plugins/tag-cloud>`_. See the :ref:`plugins`
+documentation for further information about the Pelican plugin system.
 
 Since I upgraded Pelican my pages are no longer rendered
 ========================================================

docs/importer.rst

@@ -24,8 +24,8 @@ not be converted (as Pelican also supports Markdown).
 
    Unlike Pelican, Wordpress supports multiple categories per article. These
    are imported as a comma-separated string. You have to resolve these
-   manually, or use a plugin that enables multiple categories per article
-   (like `more_categories`_).
+   manually, or use a plugin such as `More Categories`_ that enables multiple
+   categories per article.
 
 Dependencies
 ============
@@ -140,4 +140,4 @@ To test the module, one can use sample files:
 - for WordPress: https://www.wpbeginner.com/wp-themes/how-to-add-dummy-content-for-theme-development-in-wordpress/
 - for Dotclear: http://media.dotaddict.org/tda/downloads/lorem-backup.txt
 
-.. _more_categories: https://github.com/getpelican/pelican-plugins/tree/master/more_categories
+.. _More Categories: https://github.com/pelican-plugins/more-categories

docs/install.rst

@@ -1,19 +1,17 @@
 Installing Pelican
 ##################
 
-Pelican currently runs best on Python 2.7.x and 3.5+; earlier versions of
-Python are not supported.
+Pelican currently runs best on 3.6+; earlier versions of Python are not supported.
 
-You can install Pelican via several different methods. The simplest is via
-`pip <https://pip.pypa.io/en/stable/>`_::
+You can install Pelican via several different methods. The simplest is via Pip_::
 
-    pip install pelican
+    python -m pip install pelican
 
 Or, if you plan on using Markdown::
 
-    pip install pelican[Markdown]
+    python -m pip install "pelican[markdown]"
 
-(Keep in mind that operating systems will often require you to prefix the above
+(Keep in mind that some operating systems will require you to prefix the above
 command with ``sudo`` in order to install Pelican system-wide.)
 
 While the above is the simplest method, the recommended approach is to create a
@@ -26,7 +24,7 @@ session and create a new virtual environment for Pelican::
     source bin/activate
 
 Once the virtual environment has been created and activated, Pelican can be
-installed via ``pip install pelican`` as noted above. Alternatively, if you
+installed via ``python -m pip install pelican`` as noted above. Alternatively, if you
 have the project source, you can install Pelican using the distutils method::
 
     cd path-to-Pelican-source
@@ -35,7 +33,7 @@ have the project source, you can install Pelican using the distutils method::
 If you have Git installed and prefer to install the latest bleeding-edge
 version of Pelican rather than a stable release, use the following command::
 
-    pip install -e "git+https://github.com/getpelican/pelican.git#egg=pelican"
+    python -m pip install -e "git+https://github.com/getpelican/pelican.git#egg=pelican"
 
 Once Pelican is installed, you can run ``pelican --help`` to see basic usage
 options. For more detail, refer to the :doc:`Publish<publish>` section.
@@ -46,17 +44,13 @@ Optional packages
 If you plan on using `Markdown <https://pypi.org/project/Markdown/>`_ as a
 markup format, you can install Pelican with Markdown support::
 
-   pip install pelican[Markdown]
-
-Or you might need to install it a posteriori::
-
-    pip install Markdown
+    python -m pip install "pelican[markdown]"
 
 Typographical enhancements can be enabled in your settings file, but first the
 requisite `Typogrify <https://pypi.org/project/typogrify/>`_ library must be
 installed::
 
-    pip install typogrify
+    python -m pip install typogrify
 
 Dependencies
 ------------
@@ -75,9 +69,8 @@ automatically installed without any action on your part:
   broadcast signaling system
 * `unidecode <https://pypi.org/project/Unidecode/>`_, for ASCII
   transliterations of Unicode text
-* `six <https://pypi.org/project/six/>`_,  for Python 2 and 3 compatibility
   utilities
-* `MarkupSafe <https://pypi.org/project/MarkupSafe/>`_, for a markup safe
+* `MarkupSafe <https://pypi.org/project/MarkupSafe/>`_, for a markup-safe
   string implementation
 * `python-dateutil <https://pypi.org/project/python-dateutil/>`_, to read
   the date metadata
@@ -85,10 +78,10 @@ automatically installed without any action on your part:
 Upgrading
 ---------
 
-If you installed a stable Pelican release via ``pip`` and wish to upgrade to
+If you installed a stable Pelican release via Pip_ and wish to upgrade to
 the latest stable release, you can do so by adding ``--upgrade``::
 
-    pip install --upgrade pelican
+    python -m pip install --upgrade pelican
 
 If you installed Pelican via distutils or the bleeding-edge method, simply
 perform the same step to install the most recent version.
@@ -126,4 +119,5 @@ content)::
 The next step is to begin to adding content to the *content* folder that has
 been created for you.
 
+.. _Pip: https://pip.pypa.io/
 .. _virtualenv: https://virtualenv.pypa.io/en/latest/

docs/internals.rst

@@ -44,17 +44,22 @@ HTML content and some metadata.
 
 Take a look at the Markdown reader::
 
+    from pelican.readers import BaseReader
+    from pelican.utils import pelican_open
+    from markdown import Markdown
+
     class MarkdownReader(BaseReader):
-        enabled = bool(Markdown)
+        enabled = True
 
         def read(self, source_path):
             """Parse content and metadata of markdown files"""
-            text = pelican_open(source_path)
-            md_extensions = {'markdown.extensions.meta': {},
-                             'markdown.extensions.codehilite': {}}
-            md = Markdown(extensions=md_extensions.keys(),
-                          extension_configs=md_extensions)
-            content = md.convert(text)
+
+            with pelican_open(source_path) as text:
+                md_extensions = {'markdown.extensions.meta': {},
+                                 'markdown.extensions.codehilite': {}}
+                md = Markdown(extensions=md_extensions.keys(),
+                              extension_configs=md_extensions)
+                content = md.convert(text)
 
             metadata = {}
             for name, value in md.Meta.items():

docs/plugins.rst

@@ -12,8 +12,8 @@ How to use plugins
 Starting with version 4.5, Pelican moved to a new plugin structure utilizing
 namespace packages that can be easily installed via Pip_. Plugins supporting
 this structure will install under the namespace package ``pelican.plugins`` and
-can be automatically discovered by Pelican. To see a list of plugins that are
-active in your environment, run::
+can be automatically discovered by Pelican. To see a list of Pip-installed
+namespace plugins that are active in your environment, run::
 
     pelican-plugins
 
@@ -70,8 +70,8 @@ How to create plugins
 =====================
 
 Plugins are based on the concept of signals. Pelican sends signals, and plugins
-subscribe to those signals. The list of signals are defined in a subsequent
-section.
+subscribe to those signals. The list of available signals is documented in a
+subsequent section.
 
 The only rule to follow for plugins is to define a ``register`` callable, in
 which you map the signals to your plugin logic. Let's take a simple example::
@@ -94,6 +94,10 @@ which you map the signals to your plugin logic. Let's take a simple example::
     your ``register`` callable or they will be garbage-collected before the
     signal is emitted.
 
+If multiple plugins connect to the same signal, there is no way to guarantee or
+control in which order the plugins will be executed. This is a limitation
+inherited from Blinker_, the dependency Pelican uses to implement signals.
+
 Namespace plugin structure
 --------------------------
 
@@ -272,3 +276,4 @@ Adding a new generator is also really easy. You might want to have a look at
 
 .. _Pip: https://pip.pypa.io/
 .. _pelican-plugins bug #314: https://github.com/getpelican/pelican-plugins/issues/314
+.. _Blinker: https://pythonhosted.org/blinker/

docs/publish.rst

@@ -118,7 +118,7 @@ in a wide range of environments. The downside is that it must be installed
 separately. Use the following command to install Invoke, prefixing with
 ``sudo`` if your environment requires it::
 
-    pip install invoke
+    python -m pip install invoke
 
 Take a moment to open the ``tasks.py`` file that was generated in your project
 root. You will see a number of commands, any one of which can be renamed,
@@ -139,7 +139,7 @@ http://localhost:8000/::
     invoke serve
 
 To serve the generated site with automatic browser reloading every time a
-change is detected, first ``pip install livereload``, then use the
+change is detected, first ``python -m pip install livereload``, then use the
 following command::
 
     invoke livereload

docs/quickstart.rst

@@ -8,10 +8,10 @@ Installation
 ------------
 
 Install Pelican (and optionally Markdown if you intend to use it) on Python
-2.7.x or Python 3.5+ by running the following command in your preferred
-terminal, prefixing with ``sudo`` if permissions warrant::
+3.6+ by running the following command in your preferred terminal, prefixing
+with ``sudo`` if permissions warrant::
 
-    pip install pelican[Markdown]
+    python -m pip install "pelican[markdown]"
 
 Create a project
 ----------------

docs/settings.rst

@@ -9,6 +9,12 @@ line::
 If you used the ``pelican-quickstart`` command, your primary settings file will
 be named ``pelicanconf.py`` by default.
 
+You can also specify extra settings via ``-e`` / ``--extra-settings`` option
+flags, which will override default settings as well as any defined within
+settings files::
+
+    pelican content -e DELETE_OUTPUT_DIRECTORY=true
+
 .. note::
 
    When experimenting with different settings (especially the metadata ones)
@@ -270,8 +276,8 @@ Basic settings
 
    If set to True, several typographical improvements will be incorporated into
    the generated HTML via the `Typogrify
-   <https://pypi.python.org/pypi/typogrify>`_ library, which can be installed
-   via: ``pip install typogrify``
+   <https://pypi.org/project/typogrify/>`_ library, which can be installed
+   via: ``python -m pip install typogrify``
 
 .. data:: TYPOGRIFY_IGNORE_TAGS = []
 
@@ -297,10 +303,10 @@ Basic settings
    does not otherwise specify a summary. Setting to ``None`` will cause the
    summary to be a copy of the original content.
 
-.. data:: SUMMARY_END_MARKER = '…'
+.. data:: SUMMARY_END_SUFFIX = '…'
 
    When creating a short summary of an article and the result was truncated to
-   match the required word length, this will be used as the truncation marker.
+   match the required word length, this will be used as the truncation suffix.
 
 .. data:: WITH_FUTURE_DATES = True
 
@@ -770,7 +776,7 @@ Template pages
 .. data:: TEMPLATE_PAGES = None
 
    A mapping containing template pages that will be rendered with the blog
-   entries. See :ref:`template_pages`.
+   entries.
 
    If you want to generate custom pages besides your blog entries, you can
    point any Jinja2 template file with a path pointing to the file and the
@@ -1061,6 +1067,11 @@ as follows::
   )
 
 
+If you want a pattern to apply to the last page in the list, use ``-1``
+as the ``minimum_page`` value::
+
+    (-1, '{base_name}/last/', '{base_name}/last/index.html'),
+
 Translations
 ============
 
@@ -1123,10 +1134,11 @@ Ordering content
 
    Defines how the articles (``articles_page.object_list`` in the template) are
    sorted. Valid options are: metadata as a string (use ``reversed-`` prefix
-   the reverse the sort order), special option ``'basename'`` which will use
-   the basename of the file (without path) or a custom function to extract the
-   sorting key from articles. The default value, ``'reversed-date'``, will sort
-   articles by date in reverse order (i.e. newest article comes first).
+   to reverse the sort order), special option ``'basename'`` which will use
+   the basename of the file (without path), or a custom function to extract the
+   sorting key from articles. Using a value of ``'date'`` will sort articles in
+   chronological order, while the default value, ``'reversed-date'``, will sort
+   articles by date in reverse order (i.e., newest article comes first).
 
 .. data:: PAGE_ORDER_BY = 'basename'