And also provide a short guide how to build the m.css website itself.
`documentation <http://mcss.mosra.cz/>`_.
- Documentation and the website is essential part of the project and every
larger Pelican theme, plugin code or CSS contribution should be reflected
- there. The website is contained inside `site/ <site>`_ subdirectory and you
- can build and start a local version of it using Pelican by executing
- ``make devserver`` in there. The website is then available at
- http://localhost:8000. See `Pelican usage documentation <http://mcss.mosra.cz/pelican/>`_
- for more information.
-- Documentation and website content is written in reStructuredText and
+ there. Documentation and website content is written in reStructuredText and
resides in `doc/ <doc>`_ subdirectory. Please verify that all your changes
- there do not break the website build.
+ there do not break the website build; see the `README <README.rst>`_ for
+ a guide how to build it.
- Best way to contribute is by using GitHub `pull requests <https://github.com/mosra/m.css/pulls>`_
--- fork the repository and make pull request from feature branch. You can
also send patches via e-mail or contact me any other way.
*Still not convinced?* Head over to a `detailed explanation <http://mcss.mosra.cz/why/>`_
of this project goals and design decisions.
+BUILDING THE SITE
+=================
+
+**Note:** this is about building the m.css website itself, *not* about using
+m.css in your project. Check `the website <http://mcss.mosra.cz>`_ for end-user
+docs instead.*
+
+The m.css website makes use of all the m.css features, which means that it also
+needs all the possible dependencies, combined. Sorry in advance :)
+
+On ArchLinux:
+
+.. code:: sh
+
+ pacman -S texlive-most pelican python-pillow
+ cower -d python-pyphen # Build the python-pyphen package from AUR
+
+On Ubuntu you need these:
+
+.. code:: sh
+
+ sudo apt-get install texlive-base texlive-latex-extra texlive-fonts-extra
+ pip install pelican Pyphen Pillow
+
+Once you have all the dependencies, simply go to the ``site/`` subdirectory and
+start development server there. The live-reloading website will appear on
+http://localhost:8000.
+
+.. code:: sh
+
+ cd site
+ make devserver
+
+Publishing the website with ``make publish`` depends on a few patches that are
+not in any stable Pelican release yet (most importantly
+https://github.com/getpelican/pelican/pull/2246), in order to have them,
+install Pelican from my local fork instead:
+
+.. code:: sh
+
+ pip install git+https://github.com/mosra/pelican.git@mosra-master
+
CONTRIBUTING
============
# You may need sudo here
pip install pelican
-Once you have Pelican installed, create a directory for your website and
-bootstrap it:
+Note that using the m.css theme or Pelican plugins may require additional
+dependencies than just Pelican --- documentation of each lists the additional
+requirements, if any. Once you have Pelican installed, create a directory for
+your website and bootstrap it:
.. code:: sh
:gh:`m.abbr <mosra/m.css$master/pelican-plugins/m/abbr.py>`,
:gh:`m.filesize <mosra/m.css$master/pelican-plugins/m/filesize.py>`
-Click on the headings below to get to know more.
+Click on the headings below to get to know more. Note that particular plugins
+can have additional dependencies besides just Pelican, see documentation of
+each of them to see more.
`HTML sanity » <{filename}/plugins/htmlsanity.rst>`_
====================================================
M_HTMLSANITY_SMART_QUOTES = True
M_HTMLSANITY_HYPHENATION = True
+Hyphenation (see below) requires the `Pyphen <http://pyphen.org/>`_ library,
+either install it via ``pip`` or your distribution package manager or disable
+it with the above setting.
+
+.. code:: sh
+
+ pip install Pyphen
+
`What it does`_
===============
Download the `m/images.py <{filename}/plugins.rst>`_ file, put it including the
``m/`` directory into one of your :py:`PLUGIN_PATHS` and add ``m.images``
-package to your :py:`PLUGINS` in ``pelicanconf.py``. To use the image grid
-feature, in addition you need the `Pillow <https://pypi.python.org/pypi/Pillow>`_
-library installed. This plugin assumes presence of
-`m.htmlsanity <{filename}/plugins/htmlsanity.rst>`_.
+package to your :py:`PLUGINS` in ``pelicanconf.py``. This plugin assumes
+presence of `m.htmlsanity <{filename}/plugins/htmlsanity.rst>`_.
.. code:: python
PLUGINS += ['m.htmlsanity', 'm.images']
M_IMAGES_REQUIRE_ALT_TEXT = False
+To use the image grid feature (see below), in addition you need the
+`Pillow <https://pypi.python.org/pypi/Pillow>`_ library installed. Get it via
+``pip`` or your distribution package manager:
+
+.. code:: sh
+
+ pip install Pillow
+
`Images, figures`_
==================
Download the `m/math.py and m/latex2svg.py <{filename}/plugins.rst>`_ files,
put them including the ``m/`` directory into one of your :py:`PLUGIN_PATHS` and
-add :py:`m.math` package to your :py:`PLUGINS` in ``pelicanconf.py``. In
-addition you need some LaTeX distribution and `dvisvgm <http://dvisvgm.bplaced.net/>`_
-installed. This plugin assumes presence of
-`m.htmlsanity <{filename}/plugins/htmlsanity.rst>`_.
+add :py:`m.math` package to your :py:`PLUGINS` in ``pelicanconf.py``. This
+plugin assumes presence of `m.htmlsanity <{filename}/plugins/htmlsanity.rst>`_.
.. code:: python
PLUGINS += ['m.htmlsanity', 'm.math']
+In addition you need some LaTeX distribution installed. Use your distribution
+package manager, for example on Ubuntu:
+
+.. code:: sh
+
+ sudo apt-get install texlive-base texlive-latex-extra texlive-fonts-extra
+
The plugin overrides the builtin docutils
`math directive <http://docutils.sourceforge.net/docs/ref/rst/directives.html#math>`_
and `math interpreted text role <http://docutils.sourceforge.net/docs/ref/rst/roles.html#math>`_
Download the `m/code.py <{filename}/plugins.rst>`_ file, put it including the
``m/`` directory into one of your :py:`PLUGIN_PATHS` and add :py:`m.code`
-package to your :py:`PLUGINS` in ``pelicanconf.py``. In addition you need to
-have `Pygments <http://pygments.org>`_ installed. This plugin assumes presence
-of `m.htmlsanity <{filename}/plugins/htmlsanity.rst>`_.
+package to your :py:`PLUGINS` in ``pelicanconf.py``. This plugin assumes
+presence of `m.htmlsanity <{filename}/plugins/htmlsanity.rst>`_.
.. code:: python
PLUGINS += ['m-htmlsanity', 'm.code']
+In addition you need to have `Pygments <http://pygments.org>`_ installed. Get
+it via ``pip`` or your distribution package manager:
+
+.. code:: sh
+
+ pip install Pygments
+
The plugin overrides the builtin docutils
`code directive <http://docutils.sourceforge.net/docs/ref/rst/directives.html#code>`_
and `code interpreted text role <http://docutils.sourceforge.net/docs/ref/rst/roles.html#code>`_,
~cjwatson / blog.git / commitdiff