From c6d0b2abe52f37f842a8e0e65dd26eb1c048d3a9 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Sun, 5 Nov 2017 16:58:26 +0100 Subject: [PATCH] Improve documentation about additional dependencies. And also provide a short guide how to build the m.css website itself. --- CONTRIBUTING.rst | 10 +++------ README.rst | 42 +++++++++++++++++++++++++++++++++++ doc/pelican.rst | 6 +++-- doc/plugins.rst | 4 +++- doc/plugins/htmlsanity.rst | 8 +++++++ doc/plugins/images.rst | 14 ++++++++---- doc/plugins/math-and-code.rst | 25 +++++++++++++++------ 7 files changed, 88 insertions(+), 21 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index ac42defc..7f5391e0 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -18,14 +18,10 @@ Code contribution `documentation `_. - 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/ `_ 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 `_ - 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/ `_ subdirectory. Please verify that all your changes - there do not break the website build. + there do not break the website build; see the `README `_ for + a guide how to build it. - Best way to contribute is by using GitHub `pull requests `_ --- fork the repository and make pull request from feature branch. You can also send patches via e-mail or contact me any other way. diff --git a/README.rst b/README.rst index 6f9d1d18..492fe564 100644 --- a/README.rst +++ b/README.rst @@ -48,6 +48,48 @@ possible. *Still not convinced?* Head over to a `detailed explanation `_ 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 `_ 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 ============ diff --git a/doc/pelican.rst b/doc/pelican.rst index 4bfc5bb3..6fe6770f 100644 --- a/doc/pelican.rst +++ b/doc/pelican.rst @@ -53,8 +53,10 @@ want to install the Python 3 version. # 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 diff --git a/doc/plugins.rst b/doc/plugins.rst index 49318cbd..59bb21f9 100644 --- a/doc/plugins.rst +++ b/doc/plugins.rst @@ -51,7 +51,9 @@ and restart Pelican. Download the plugins below or :gh:`m.abbr `, :gh:`m.filesize ` -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>`_ ==================================================== diff --git a/doc/plugins/htmlsanity.rst b/doc/plugins/htmlsanity.rst index 3353a60e..26d269f1 100644 --- a/doc/plugins/htmlsanity.rst +++ b/doc/plugins/htmlsanity.rst @@ -58,6 +58,14 @@ including the ``m/`` directory into one of your :py:`PLUGIN_PATHS` and add M_HTMLSANITY_SMART_QUOTES = True M_HTMLSANITY_HYPHENATION = True +Hyphenation (see below) requires the `Pyphen `_ 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`_ =============== diff --git a/doc/plugins/images.rst b/doc/plugins/images.rst index 9bd69b31..24570008 100644 --- a/doc/plugins/images.rst +++ b/doc/plugins/images.rst @@ -50,16 +50,22 @@ beautiful image galleries. 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 `_ -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 `_ library installed. Get it via +``pip`` or your distribution package manager: + +.. code:: sh + + pip install Pillow + `Images, figures`_ ================== diff --git a/doc/plugins/math-and-code.rst b/doc/plugins/math-and-code.rst index 131fea30..01a71f8f 100644 --- a/doc/plugins/math-and-code.rst +++ b/doc/plugins/math-and-code.rst @@ -52,15 +52,20 @@ rendering directly from your :abbr:`reST ` sources. 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 `_ -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 `_ and `math interpreted text role `_ @@ -125,14 +130,20 @@ want to add additional CSS classes, derive a custom role from it. 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 `_ 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 `_ installed. Get +it via ``pip`` or your distribution package manager: + +.. code:: sh + + pip install Pygments + The plugin overrides the builtin docutils `code directive `_ and `code interpreted text role `_, -- 2.30.2