github/pelican
1
0
Fork 1
mirror of https://github.com/getpelican/pelican.git synced 2025-10-15 20:28:56 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Docs: Reflow to 79 char line limit

Browse source
This commit is contained in:
MinchinWeb 2018-11-02 20:53:15 -06:00
commit f595741b8e
16 changed files with 481 additions and 460 deletions
Download patch file Download diff file Expand all files Collapse all files

40
docs/internals.rst
View file

@ -1,8 +1,8 @@
Pelican internals
#################
This section describe how Pelican works internally. As you'll see, it's
quite simple, but a bit of documentation doesn't hurt. :)
This section describe how Pelican works internally. As you'll see, it's quite
simple, but a bit of documentation doesn't hurt. :)
You can also find in the :doc:`report` section an excerpt of a report the
original author wrote with some software design information.
@ -13,9 +13,8 @@ Overall structure
=================
What Pelican does is take a list of files and process them into some sort of
output. Usually, the input files are reStructuredText and Markdown
files, and the output is a blog, but both input and output can be anything you
want.
output. Usually, the input files are reStructuredText and Markdown files, and
the output is a blog, but both input and output can be anything you want.
The logic is separated into different classes and concepts:
@ -27,9 +26,10 @@ The logic is separated into different classes and concepts:
reStructuredText for now, but the system is extensible). Given a file, they
return metadata (author, tags, category, etc.) and content (HTML-formatted).
* **Generators** generate the different outputs. For instance, Pelican comes with
``ArticlesGenerator`` and ``PageGenerator``. Given a configuration, they can do
whatever they want. Most of the time, it's generating files from inputs.
* **Generators** generate the different outputs. For instance, Pelican comes
with ``ArticlesGenerator`` and ``PageGenerator``. Given a configuration, they
can do whatever they want. Most of the time, it's generating files from
inputs.
* Pelican also uses templates, so it's easy to write your own theme. The
syntax is `Jinja2 <http://jinja.pocoo.org/>`_ and is very easy to learn, so
@ -38,9 +38,9 @@ The logic is separated into different classes and concepts:
How to implement a new reader?
==============================
Is there an awesome markup language you want to add to Pelican?
Well, the only thing you have to do is to create a class with a ``read``
method that returns HTML content and some metadata.
Is there an awesome markup language you want to add to Pelican? Well, the only
thing you have to do is to create a class with a ``read`` method that returns
HTML content and some metadata.
Take a look at the Markdown reader::
@ -65,17 +65,17 @@ Take a look at the Markdown reader::
Simple, isn't it?
If your new reader requires additional Python dependencies, then you should wrap
their ``import`` statements in a ``try...except`` block. Then inside the reader's
class, set the ``enabled`` class attribute to mark import success or failure.
This makes it possible for users to continue using their favourite markup method
without needing to install modules for formats they don't use.
If your new reader requires additional Python dependencies, then you should
wrap their ``import`` statements in a ``try...except`` block. Then inside the
reader's class, set the ``enabled`` class attribute to mark import success or
failure. This makes it possible for users to continue using their favourite
markup method without needing to install modules for formats they don't use.
How to implement a new generator?
=================================
Generators have two important methods. You're not forced to create
both; only the existing ones will be called.
Generators have two important methods. You're not forced to create both; only
the existing ones will be called.
* ``generate_context``, that is called first, for all the generators.
Do whatever you have to do, and update the global context if needed. This
@ -89,5 +89,5 @@ both; only the existing ones will be called.
generating the output. :) It's here that you may want to look at the context
and call the methods of the ``writer`` object that is passed as the first
argument of this function. In the ``PageGenerator`` example, this method will
look at all the pages recorded in the global context and output a file on
the disk (using the writer method ``write_file``) for each page encountered.
look at all the pages recorded in the global context and output a file on the
disk (using the writer method ``write_file``) for each page encountered.