From 4d890687be067037df92e74357fa35a97cd18ade Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Tue, 2 Apr 2019 23:48:31 +0200 Subject: [PATCH] doc: adapted site to project organization changes. --- doc/admire/math.rst | 2 +- doc/build-status.html.in | 2 +- doc/css/page-layout.rst | 2 +- doc/documentation.rst | 80 +++++++++++ doc/documentation/doxygen-test.rst | 6 +- doc/documentation/doxygen.rst | 67 +++------ doc/index.rst | 2 +- doc/pelican.rst | 132 ------------------ doc/plugins.rst | 36 +++-- doc/plugins/components-test.rst | 2 +- doc/plugins/components.rst | 17 ++- doc/plugins/htmlsanity.rst | 15 +- doc/plugins/images-test.rst | 2 +- doc/plugins/images.rst | 18 ++- doc/plugins/links.rst | 37 +++-- doc/plugins/math-and-code-test.rst | 2 +- doc/plugins/math-and-code.rst | 40 ++++-- doc/plugins/metadata.rst | 21 +-- doc/plugins/plots-and-graphs-test.rst | 2 +- doc/plugins/plots-and-graphs.rst | 29 ++-- doc/themes.rst | 58 ++++++++ doc/{pelican/theme.rst => themes/pelican.rst} | 104 ++++++++++++-- .../writing-rst-content.rst} | 19 +-- doc/why.rst | 9 +- documentation/test_doxygen/__init__.py | 1 - site/pelicanconf.py | 21 +-- 26 files changed, 440 insertions(+), 286 deletions(-) create mode 100644 doc/documentation.rst delete mode 100644 doc/pelican.rst create mode 100644 doc/themes.rst rename doc/{pelican/theme.rst => themes/pelican.rst} (91%) rename doc/{pelican/writing-content.rst => themes/writing-rst-content.rst} (96%) diff --git a/doc/admire/math.rst b/doc/admire/math.rst index a04d3440..b075fd89 100644 --- a/doc/admire/math.rst +++ b/doc/admire/math.rst @@ -106,7 +106,7 @@ m.css math LaTeX formulas to vector graphics locally, your viewers are saved from needless HTTP requests and heavy JavaScript processing. - .. button-success:: {filename}/pelican.rst + .. button-success:: {filename}/themes/pelican.rst :class: m-fullwidth Start using Pelican diff --git a/doc/build-status.html.in b/doc/build-status.html.in index f3cd1369..3d28d7f6 100644 --- a/doc/build-status.html.in +++ b/doc/build-status.html.in @@ -19,7 +19,7 @@  
  - Pelican plugins + Plugins Graph rendering diff --git a/doc/css/page-layout.rst b/doc/css/page-layout.rst index d08ef2c2..7035779f 100644 --- a/doc/css/page-layout.rst +++ b/doc/css/page-layout.rst @@ -49,7 +49,7 @@ active section highlighting and more. .. note-success:: The whole CSS page layout functionality is also available through a - `m.css Pelican theme <{filename}/pelican/theme.rst>`_. Check it out! + `m.css Pelican theme <{filename}/themes/pelican.rst>`_. Check it out! .. contents:: :class: m-block m-default diff --git a/doc/documentation.rst b/doc/documentation.rst new file mode 100644 index 00000000..8f7d653f --- /dev/null +++ b/doc/documentation.rst @@ -0,0 +1,80 @@ +.. + This file is part of m.css. + + Copyright © 2017, 2018, 2019 Vladimír VondruÅ¡ + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. +.. + +Doc generators +############## + +m.css is not just for static sites and blogs --- there's a need for a modern, +lightweight and mobile-friendly layout for API documentation as well. The m.css +documentation generators are defined by their first-class search functionality +and clutter-free output, favoring human-produced documentation over +autogenerated content. + +.. button-success:: https://doc.magnum.graphics + + Live demo + + doc.magnum.graphics + +`Features`_ +=========== + +All m.css documentation themes share the following features: + +- Modern, lightweight and mobile-friendly HTML5 markup +- Minimalistic design without unnecessary chrome and UI elements +- Focused on presenting the actual written documentation while reducing + questionable auto-generated content +- Math rendered as embedded SVG instead of raster images / MathJax, making + use of the `m.math <{filename}/plugins/math-and-code.rst#math>`_ plugin +- Graphviz / Dot diagrams rendered as embedded SVG, as implemented in + `m.dot <{filename}/plugins/plots-and-graphs.rst#graphs>`_ +- Using Pygments for better code highlighting, courtesy of the + `m.code <{filename}/plugins/math-and-code.rst#code>`_ plugin + +`Search`_ +--------- + +- Vastly superior search capabilities with immediate feedback +- Search anywhere from a page by opening a popup using a hotkey +- Lookahead with instant feedback without requiring any server-side backend +- Search for symbols using any prefix +- Fully controllable by keyboard + +.. image:: {static}/static/opengl-search.png + +.. note-success:: + + If you want to know more, the search functionality implementation and + features are detailed + `in this blog post `_. + +`Doxygen C++ theme » <{filename}/documentation/doxygen.rst>`_ +============================================================= + +More than just a theme --- taking the XML output produced by Doxygen, cleaning +it up, reducing the autogenerated clutter, while making it mobile-friendly and +extending it with better content layouting capabilities and improved support +for C++11 and beyond. Fully compatible with Doxygen URL format and tag files to +avoid broken links once you switch. diff --git a/doc/documentation/doxygen-test.rst b/doc/documentation/doxygen-test.rst index 3d6f5c7d..441495c9 100644 --- a/doc/documentation/doxygen-test.rst +++ b/doc/documentation/doxygen-test.rst @@ -25,8 +25,10 @@ Test #### -:save_as: doxygen/test/index.html -:breadcrumb: {filename}/doxygen.rst Doxygen theme +:save_as: documentation/doxygen/test/index.html +:breadcrumb: + {filename}/documentation.rst Doc themes + {filename}/documentation/doxygen.rst Doxygen :css: {static}/static/m-dark.doxygen.compiled.css Lists diff --git a/doc/documentation/doxygen.rst b/doc/documentation/doxygen.rst index 3c183ce0..992069e2 100644 --- a/doc/documentation/doxygen.rst +++ b/doc/documentation/doxygen.rst @@ -22,9 +22,11 @@ DEALINGS IN THE SOFTWARE. .. -Doxygen theme -############# +Doxygen C++ theme +################# +:alias: /doxygen/index.html +:breadcrumb: {filename}/documentation.rst Doc generators :summary: A modern, mobile-friendly drop-in replacement for the stock Doxygen HTML output with a first-class search functionality @@ -76,13 +78,13 @@ switch. The base is contained in a single Python script and related style/template files, for advanced features such as math rendering it'll make use of internals of some `m.css plugins <{filename}/plugins.rst>`_. Clone -:gh:`the m.css GitHub repository ` and look into -the ``doxygen/`` directory: +:gh:`the m.css GitHub repository ` and look +into the ``documentation/`` directory: .. code:: sh git clone git://github.com/mosra/m.css - cd m.css/doxygen + cd m.css/documentation The script requires Python 3.6, depends on `Jinja2 `_ for templating and `Pygments `_ for code block @@ -125,12 +127,12 @@ inside: This will derive the configuration from the original ``Doxyfile``, disables builtin Doxygen HTML output and enables XML output instead, with some unneeded -features disabled for faster processing. Now run ``dox2html5.py`` and point it +features disabled for faster processing. Now run ``doxygen.py`` and point it to your ``Doxyfile-mcss``: .. code:: sh - ./dox2html5.py path/to/your/Doxyfile-mcss + ./doxygen.py path/to/your/Doxyfile-mcss It will run ``doxygen`` to generate the XML output, processes it and generates the HTML output in the configured output directory. After the script is done, @@ -142,38 +144,13 @@ If you see something unexpected or not see something expected, check the `Features`_ =========== +In addition to features `shared by all doc generators <{filename}/documentation.rst#features>`_: + - Modern, valid, mobile-friendly HTML5 markup without table layouts -- Minimalistic design without unnecessary chrome and UI elements - URLs fully compatible with stock Doxygen HTML output to preserve existing links - Focused on presenting the actual written documentation while reducing questionable auto-generated content -- Math rendered as embedded SVG instead of raster images / MathJax. The - supported feature set is equivalent to the `m.math Pelican plugin <{filename}/plugins/math-and-code.rst#math>`_, - see its documentation for more information. -- Graphviz / Dot diagrams rendered as embedded SVG. The supported feature set - is equivalent to the `m.dot Pelican plugin <{filename}/plugins/plots-and-graphs.rst#graphs>`_, - see its documentation for more information. -- Uses Pygments for better code highlighting. The supported feature set is - equivalent to the `m.code Pelican plugin <{filename}/plugins/math-and-code.rst#code>`_, - see its documentation for more information. - -`Search`_ ---------- - -- Vastly superior search capabilities with immediate feedback -- Search anywhere from a page by opening a popup using a hotkey -- Lookahead with instant feedback without requiring any server-side backend -- Search for symbols using any prefix -- Fully controllable by keyboard - -.. image:: {static}/static/opengl-search.png - -.. note-success:: - - If you want to know more, the search functionality implementation and - features are detailed - `in this blog post `_. `Important differences to stock HTML output`_ --------------------------------------------- @@ -289,14 +266,14 @@ Variable Description external references :ini:`HTML_EXTRA_STYLESHEET` List of CSS files to include. Relative paths are searched relative to the Doxyfile base dir - and to the ``dox2html5.py`` script dir as a + and to the ``doxygen.py`` script dir as a fallback. See `Theme selection`_ for more information. :ini:`HTML_EXTRA_FILES` List of extra files to copy (for example additional CSS files that are :css:`@import`\ ed from the primary one). Relative paths are searched relative to the Doxyfile base dir and - to the ``dox2html5.py`` script dir as a + to the ``doxygen.py`` script dir as a fallback. :ini:`DOT_FONTNAME` Font name to use for ``@dot`` and ``@dotfile`` commands. To ensure consistent look with the @@ -333,7 +310,7 @@ Variable Description :html:``. If empty, no :html:`` tag is rendered. Relative paths are searched relative to the Doxyfile - base dir and to the ``dox2html5.py`` script + base dir and to the ``doxygen.py`` script dir as a fallback. See `Theme selection`_ for more information. :ini:`M_LINKS_NAVBAR1` Left navbar column links. See @@ -1203,13 +1180,13 @@ suffix of the title. .. code:: sh - ./dox2html5.py [-h] [--templates TEMPLATES] [--wildcard WILDCARD] - [--index-pages INDEX_PAGES [INDEX_PAGES ...]] - [--no-doxygen] [--search-no-subtree-merging] - [--search-no-lookahead-barriers] - [--search-no-prefix-merging] [--sort-globbed-files] - [--debug] - doxyfile + ./doxygen.py [-h] [--templates TEMPLATES] [--wildcard WILDCARD] + [--index-pages INDEX_PAGES [INDEX_PAGES ...]] + [--no-doxygen] [--search-no-subtree-merging] + [--search-no-lookahead-barriers] + [--search-no-prefix-merging] [--sort-globbed-files] + [--debug] + doxyfile Arguments: @@ -1282,7 +1259,7 @@ file / symbol tree: ... -To help you debugging this, run ``dox2html5.py`` with the ``--debug`` option. +To help you debugging this, run ``doxygen.py`` with the ``--debug`` option. and look for entries that look like below. Because there are many false positives, this information is not present in the non-verbose output. diff --git a/doc/index.rst b/doc/index.rst index e1b3edf0..239fd237 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -86,7 +86,7 @@ m.css don't need forms, progressbars, popups, dropdowns or other cruft. You want fast iteration times. - .. button-warning:: {filename}/pelican.rst + .. button-warning:: {filename}/themes/pelican.rst :class: m-fullwidth Use it with Pelican diff --git a/doc/pelican.rst b/doc/pelican.rst deleted file mode 100644 index d5b651d4..00000000 --- a/doc/pelican.rst +++ /dev/null @@ -1,132 +0,0 @@ -.. - This file is part of m.css. - - Copyright © 2017, 2018, 2019 Vladimír VondruÅ¡ - - Permission is hereby granted, free of charge, to any person obtaining a - copy of this software and associated documentation files (the "Software"), - to deal in the Software without restriction, including without limitation - the rights to use, copy, modify, merge, publish, distribute, sublicense, - and/or sell copies of the Software, and to permit persons to whom the - Software is furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be included - in all copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL - THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING - FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER - DEALINGS IN THE SOFTWARE. -.. - -Pelican -####### - -.. role:: sh(code) - :language: sh - -`Pelican `_ is a static site generator powered by -Python and unlike most other static site generators, it uses -`reStructuredText `_ instead of -Markdown for authoring content. m.css provides a theme for it, together with a -set of useful plugins. - -.. note-warning:: - - Please, in this case, don't judge the book by its cover --- the - :abbr:`reST ` website might look like it was made in 1992 - and never updated since, but believe me, it's a remarkably designed format. - Once you dive into it, you will not want to go back to Markdown. - -`Quick start`_ -============== - -Install Pelican either via ``pip`` or using your system package manager. - -.. note-danger:: - - In order to use the m.css `theme <{filename}/pelican/theme.rst>`_ or - `plugins <{filename}/plugins.rst>`_ later, you need to install Pelican 4 - and the Python 3 version of it. Most of the plugins work with Python 3.4, - while some (such as the - `math plugin <{filename}/plugins/math-and-code.rst#math>`_) need 3.5. - Python 2 is not supported and compatibility with Pelican 3.7 has been - dropped. - -.. code:: sh - - # You may need sudo here - pip3 install pelican - -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 - - mkdir ~/my-cool-site/ - cd ~/my-cool-site/ - pelican-quickstart - -This command will ask you a few questions. You don't need the URL prefix for -now, but you definitely want a Makefile and an auto-reload script to be -generated. Leave the rest at its defaults. Once the quickstart script finishes, -you can run the auto-reloading like this: - -.. todo: remove the auto-reload script when Pelican has it builtin - -.. code:: sh - - make devserver - -It will print quite some output about processing things and serving the data to -the console. Open your fresh website at http://localhost:8000. The site is now -empty, so let's create a simple article and put it into ``content/`` -subdirectory with a ``.rst`` extension. For this example that would be -``~/my-cool-site/content/my-cool-article.rst``: - -.. code:: rst - - My cool article - ############### - - :date: 2017-09-14 23:04 - :category: Cool things - :tags: cool, article, mine - :summary: This article has a cool summary. - - This article has not only cool summary, but also has cool contents. Lorem? - *Ipsum.* `Hi, google! `_ - -If you did everything right, the auto-reload script should pick the file up and -process it (check the console output). Then it's just a matter of refreshing -your browser to see it on the page. - -.. note-info:: - - Currently, if Pelican encounters an error when processing the article, it - will just stop refreshing and you need to restart it by executing - :sh:`make devserver` again. - -*That's it!* Congratulations, you successfully made your first steps with -Pelican. The default theme might be a bit underwhelming, so let's fix that. -Click on the headers below to get to know more. - -`Writing content » <{filename}/pelican/writing-content.rst>`_ -============================================================= - -Quick guide and tips for writing content using :abbr:`reST `. -Chances are that you already know your way around from Sphinx or other -documentation tools, nevertheless there are some hidden tricks that you might -not know about yet. - -`Theme » <{filename}/pelican/theme.rst>`_ -========================================= - -A feature-packed theme with modern and responsive design that exposes all of -m.css functionality with goodies on top such as social meta tags, breadcrumb -navigation and more. diff --git a/doc/plugins.rst b/doc/plugins.rst index 88303de2..ddf585f2 100644 --- a/doc/plugins.rst +++ b/doc/plugins.rst @@ -22,29 +22,33 @@ DEALINGS IN THE SOFTWARE. .. -Pelican plugins -############### +Plugins +####### .. role:: py(code) :language: py -The `Pelican theme <{filename}/pelican/theme.rst>`_ provided by m.css uses only -a part of the functionality on its own, the rest is exposed by various plugins. +In addition to providing a theme for `Pelican <{filename}/themes/pelican.rst>`_ +or `Doxygen <{filename}/documentation/doxygen.rst>`_ that styles the overall +page layout and basic typography, m.css also contains a collection of plugins, +extending the capabilities futher. `Usage`_ ======== -Each plugin is a standalone ``*.py`` file that is meant to be downloaded and -put into a ``m/`` subdirectory into one of your :py:`PLUGIN_PATHS`. Then you -add given :py:`m.something` package to your :py:`PLUGINS` in ``pelicanconf.py`` -and restart Pelican. Download the plugins below or -:gh:`grab the whole Git repository `: +For use with Pelican, each plugin is a standalone ``*.py`` file that is meant +to be downloaded and put into a ``m/`` subdirectory into one of your +:py:`PLUGIN_PATHS`. Then you add given :py:`m.something` package to your +:py:`PLUGINS` in ``pelicanconf.py`` and restart Pelican. Download the plugins +below or :gh:`grab the whole Git repository `: - :gh:`m.htmlsanity ` - :gh:`m.components ` - :gh:`m.images ` -- :gh:`m.math ` (needs also :gh:`latex2svg `), - :gh:`m.code ` (needs also :gh:`ansilexer `) +- :gh:`m.math ` (needs also + :gh:`latex2svg `), + :gh:`m.code ` (needs also + :gh:`ansilexer `) - :gh:`m.plots `, :gh:`m.dot ` - :gh:`m.link `, @@ -57,9 +61,13 @@ and restart Pelican. Download the plugins below or :gh:`m.alias ` - :gh:`m.metadata ` -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. +All plugins that make sense in the context of the +`Doxygen theme <{filename}/documentation/doxygen.rst>`_ are implicitly exposed +to it, without needing to explicitly enable them. + +Note that particular plugins can have additional dependencies, see +documentation of each of them to see more. Click on the headings below to get +to know more. `HTML sanity » <{filename}/plugins/htmlsanity.rst>`_ ==================================================== diff --git a/doc/plugins/components-test.rst b/doc/plugins/components-test.rst index ce5af3ad..ade7c512 100644 --- a/doc/plugins/components-test.rst +++ b/doc/plugins/components-test.rst @@ -26,7 +26,7 @@ Test #### :save_as: plugins/components/test/index.html -:breadcrumb: {filename}/plugins.rst Pelican plugins +:breadcrumb: {filename}/plugins.rst Plugins {filename}/plugins/components.rst Components Should match the rendering of diff --git a/doc/plugins/components.rst b/doc/plugins/components.rst index fc4b1611..c74150b8 100644 --- a/doc/plugins/components.rst +++ b/doc/plugins/components.rst @@ -25,12 +25,12 @@ Components ########## -:breadcrumb: {filename}/plugins.rst Pelican plugins +:breadcrumb: {filename}/plugins.rst Plugins :footer: .. note-dim:: :class: m-text-center - `« HTML sanity <{filename}/plugins/htmlsanity.rst>`_ | `Pelican plugins <{filename}/plugins.rst>`_ | `Images » <{filename}/plugins/images.rst>`_ + `« HTML sanity <{filename}/plugins/htmlsanity.rst>`_ | `Plugins <{filename}/plugins.rst>`_ | `Images » <{filename}/plugins/images.rst>`_ .. role:: html(code) :language: html @@ -50,6 +50,9 @@ which is the most important thing when authoring content. `How to use`_ ============= +`Pelican`_ +---------- + Download the `m/components.py <{filename}/plugins.rst>`_ file, put it including the ``m/`` directory into one of your :py:`PLUGIN_PATHS` and add :py:`m.components` package to your :py:`PLUGINS` in ``pelicanconf.py``. This @@ -59,6 +62,16 @@ plugin assumes presence of `m.htmlsanity <{filename}/plugins/htmlsanity.rst>`_. PLUGINS += ['m.htmlsanity', 'm.components'] +`Doxygen theme`_ +---------------- + +Unfortunately, due to a lack of extensibility of the Doxygen markup language, +it's not possible to provide the components through easy-to-use commands. All +you have is the ability to apply CSS classes using ``@m_class``, ``@m_span`` +and ``@m_div``. See the +`Doxygen theme-specific commands `_ +for more information. + `Transitions`_ ============== diff --git a/doc/plugins/htmlsanity.rst b/doc/plugins/htmlsanity.rst index 44b1f496..a3367ea5 100644 --- a/doc/plugins/htmlsanity.rst +++ b/doc/plugins/htmlsanity.rst @@ -25,12 +25,12 @@ HTML sanity ########### -:breadcrumb: {filename}/plugins.rst Pelican plugins +:breadcrumb: {filename}/plugins.rst Plugins :footer: .. note-dim:: :class: m-text-center - `Pelican plugins <{filename}/plugins.rst>`_ | `Components » <{filename}/plugins/components.rst>`_ + `Plugins <{filename}/plugins.rst>`_ | `Components » <{filename}/plugins/components.rst>`_ .. role:: html(code) :language: html @@ -50,6 +50,9 @@ the current century. `How to use`_ ============= +`Pelican`_ +---------- + Download the `m/htmlsanity.py <{filename}/plugins.rst>`_ file, put it including the ``m/`` directory into one of your :py:`PLUGIN_PATHS` and add :py:`m.htmlsanity` package to your :py:`PLUGINS` in ``pelicanconf.py``. @@ -68,6 +71,12 @@ it with the above setting. pip3 install Pyphen +`Doxygen theme`_ +---------------- + +The Doxygen theme generates the HTML output directly, without docutils in the +mix, which means there's no need for this particular plugin there. + `What it does`_ =============== @@ -363,7 +372,7 @@ from passed text. The ``enable`` argument works the same as with the There are already `numerous `_ `Pelican `_ -`plugins `_ +`plugins `__ that try to do similar things, but they *attempt* to fix it using BeautifulSoup on top of the generated HTML. That's a horrendous thing to do, so why not just prevent the horror from happening? diff --git a/doc/plugins/images-test.rst b/doc/plugins/images-test.rst index e06afb18..d599cbae 100644 --- a/doc/plugins/images-test.rst +++ b/doc/plugins/images-test.rst @@ -26,7 +26,7 @@ Test #### :save_as: plugins/images/test/index.html -:breadcrumb: {filename}/plugins.rst Pelican plugins +:breadcrumb: {filename}/plugins.rst Plugins {filename}/plugins/images.rst Images `Images, figures`_ diff --git a/doc/plugins/images.rst b/doc/plugins/images.rst index 3c5e021a..3ced8805 100644 --- a/doc/plugins/images.rst +++ b/doc/plugins/images.rst @@ -25,12 +25,12 @@ Images ###### -:breadcrumb: {filename}/plugins.rst Pelican plugins +:breadcrumb: {filename}/plugins.rst Plugins :footer: .. note-dim:: :class: m-text-center - `« Components <{filename}/plugins/components.rst>`_ | `Pelican plugins <{filename}/plugins.rst>`_ | `Math and code » <{filename}/plugins/math-and-code.rst>`_ + `« Components <{filename}/plugins/components.rst>`_ | `Plugins <{filename}/plugins.rst>`_ | `Math and code » <{filename}/plugins/math-and-code.rst>`_ .. role:: css(code) :language: css @@ -48,6 +48,9 @@ beautiful image galleries. `How to use`_ ============= +`Pelican`_ +---------- + 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``. This plugin assumes @@ -66,6 +69,17 @@ library installed. Get it via ``pip`` or your distribution package manager: pip3 install Pillow +`Doxygen theme`_ +---------------- + +The Doxygen theme makes the builtin ``@image`` command behave similarly to +the :rst:`.. image::` directive of this plugin, if you add a title to it, it +behaves like :rst:`.. figure::`. It's possible to add extra CSS classes by +placing ``@m_class`` in a paragraph before the actual image, see the +`Doxygen theme-specific commands `_ +for more information. The :rst:`.. image-grid::` functionality is not available +in the Doxygen theme. + `Images, figures`_ ================== diff --git a/doc/plugins/links.rst b/doc/plugins/links.rst index b6e6cc3f..e350dc5d 100644 --- a/doc/plugins/links.rst +++ b/doc/plugins/links.rst @@ -25,12 +25,12 @@ Links and other ############### -:breadcrumb: {filename}/plugins.rst Pelican plugins +:breadcrumb: {filename}/plugins.rst Plugins :footer: .. note-dim:: :class: m-text-center - `« Plots and graphs <{filename}/plugins/plots-and-graphs.rst>`_ | `Pelican plugins <{filename}/plugins.rst>`_ | `Metadata » <{filename}/plugins/metadata.rst>`_ + `« Plots and graphs <{filename}/plugins/plots-and-graphs.rst>`_ | `Plugins <{filename}/plugins.rst>`_ | `Metadata » <{filename}/plugins/metadata.rst>`_ .. role:: html(code) :language: html @@ -38,6 +38,8 @@ Links and other :language: py .. role:: rst(code) :language: rst +.. role:: ini(code) + :language: ini m.css plugins make linking to external content almost too easy. If your website is about coding, chances are quite high that you will be linking to @@ -52,12 +54,19 @@ own requirements. .. contents:: :class: m-block m-default +.. note-warning:: + + None of these plugins can be supported in the Doxygen theme (except the + `Doxygen documentation`_ links, which are builtin). Instead, you can have + some limited templating options by adding a custom command to the + :ini:`ALIASES` Doxyfile option. + `Stylable links`_ ================= -Download the `m/link.py <{filename}/plugins.rst>`_ file, put it including the -``m/`` directory into one of your :py:`PLUGIN_PATHS` and add :py:`m.link` -package to your :py:`PLUGINS` in ``pelicanconf.py``: +For Pelican, download the `m/link.py <{filename}/plugins.rst>`_ file, put it +including the ``m/`` directory into one of your :py:`PLUGIN_PATHS` and add +:py:`m.link` package to your :py:`PLUGINS` in ``pelicanconf.py``: .. code:: python @@ -84,7 +93,7 @@ additional CSS classes. At the moment the plugin knows only external URLs. `GitHub`_ ========= -Download the `m/gh.py <{filename}/plugins.rst>`_ file, put it +For Pelican, download the `m/gh.py <{filename}/plugins.rst>`_ file, put it including the ``m/`` directory into one of your :py:`PLUGIN_PATHS` and add :py:`m.gh` package to your :py:`PLUGINS` in ``pelicanconf.py``: @@ -141,7 +150,7 @@ CSS classes by deriving the role and adding the :rst:`:class:` option. `OpenGL functions and extensions`_ ================================== -Download the `m/gl.py <{filename}/plugins.rst>`_ file, put it +For Pelican, download the `m/gl.py <{filename}/plugins.rst>`_ file, put it including the ``m/`` directory into one of your :py:`PLUGIN_PATHS` and add :py:`m.gl` package to your :py:`PLUGINS` in ``pelicanconf.py``: @@ -189,7 +198,7 @@ and adding the :rst:`:class:` option. `Vulkan functions and extensions`_ ================================== -Download the `m/vk.py <{filename}/plugins.rst>`_ file, put it +For Pelican, download the `m/vk.py <{filename}/plugins.rst>`_ file, put it including the ``m/`` directory into one of your :py:`PLUGIN_PATHS` and add :py:`m.vk` package to your :py:`PLUGINS` in ``pelicanconf.py``: @@ -234,7 +243,7 @@ possible to specify alternate link text using the well-known syntax. `Doxygen documentation`_ ======================== -Download the `m/dox.py <{filename}/plugins.rst>`_ file, put it +For Pelican, download the `m/dox.py <{filename}/plugins.rst>`_ file, put it including the ``m/`` directory into one of your :py:`PLUGIN_PATHS` and add :py:`m.dox` package to your plugins in ``pelicanconf.py``. The plugin uses Doxygen tag files to get a list of linkable symbols and you need to provide @@ -313,8 +322,8 @@ external not), you could do this: .. note-success:: If you haven't noticed yet, m.css also provides a - `full-featured Doxygen theme <{filename}/doxygen.rst>`_ with first-class - search functionality. Check it out! + `full-featured Doxygen theme <{filename}/documentation/doxygen.rst>`_ with + first-class search functionality. Check it out! `Abbreviations`_ ================ @@ -322,7 +331,7 @@ external not), you could do this: While not exactly a link but rather a way to produce correct :html:`` elements, it belongs here as it shares a similar syntax. -Download the `m/abbr.py <{filename}/plugins.rst>`_ file, put it +For Pelican, download the `m/abbr.py <{filename}/plugins.rst>`_ file, put it including the ``m/`` directory into one of your :py:`PLUGIN_PATHS` and add :py:`m.abbr` package to your :py:`PLUGINS` in ``pelicanconf.py``. This plugin assumes presence of `m.htmlsanity <{filename}/plugins/htmlsanity.rst>`_. @@ -362,7 +371,7 @@ role and adding the :rst:`:class:` option. Okay, this is not a link at all, but --- sometimes you might want to display size of a file, for example to tell the users how big the download will be. -Download the `m/filesize.py <{filename}/plugins.rst>`_ file, put it +For Pelican, ownload the `m/filesize.py <{filename}/plugins.rst>`_ file, put it including the ``m/`` directory into one of your :py:`PLUGIN_PATHS` and add :py:`m.filesize` package to your :py:`PLUGINS` in ``pelicanconf.py``. @@ -403,7 +412,7 @@ and preserving old links for backwards compatibility is a vital thing for user friendliness. This plugin allows you to create a redirect alias URLs for your pages and articles. -Download the `m/alias.py <{filename}/plugins.rst>`_ file, put it +For Pelican, download the `m/alias.py <{filename}/plugins.rst>`_ file, put it including the ``m/`` directory into one of your :py:`PLUGIN_PATHS` and add :py:`m.alias` package to your :py:`PLUGINS` in ``pelicanconf.py``. This plugin assumes presence of `m.htmlsanity <{filename}/plugins/htmlsanity.rst>`_. diff --git a/doc/plugins/math-and-code-test.rst b/doc/plugins/math-and-code-test.rst index b30694a5..8000c820 100644 --- a/doc/plugins/math-and-code-test.rst +++ b/doc/plugins/math-and-code-test.rst @@ -26,7 +26,7 @@ Test #### :save_as: plugins/math-and-code/test/index.html -:breadcrumb: {filename}/plugins.rst Pelican plugins +:breadcrumb: {filename}/plugins.rst Plugins {filename}/plugins/math-and-code.rst Math and code Math diff --git a/doc/plugins/math-and-code.rst b/doc/plugins/math-and-code.rst index 03b0ce43..049a330c 100644 --- a/doc/plugins/math-and-code.rst +++ b/doc/plugins/math-and-code.rst @@ -25,12 +25,12 @@ Math and code ############# -:breadcrumb: {filename}/plugins.rst Pelican plugins +:breadcrumb: {filename}/plugins.rst Plugins :footer: .. note-dim:: :class: m-text-center - `« Images <{filename}/plugins/images.rst>`_ | `Pelican plugins <{filename}/plugins.rst>`_ | `Plots and graphs » <{filename}/plugins/plots-and-graphs.rst>`_ + `« Images <{filename}/plugins/images.rst>`_ | `Plugins <{filename}/plugins.rst>`_ | `Plots and graphs » <{filename}/plugins/plots-and-graphs.rst>`_ .. role:: css(code) :language: css @@ -52,10 +52,11 @@ rendering directly from your :abbr:`reST ` sources. `Math`_ ======= -Download the `m/math.py and 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``. This plugin -assumes presence of `m.htmlsanity <{filename}/plugins/htmlsanity.rst>`_. +For Pelican, download the `m/math.py and 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``. This plugin assumes presence of +`m.htmlsanity <{filename}/plugins/htmlsanity.rst>`_. .. note-danger:: @@ -68,6 +69,15 @@ assumes presence of `m.htmlsanity <{filename}/plugins/htmlsanity.rst>`_. M_MATH_RENDER_AS_CODE = False M_MATH_CACHE_FILE = 'm.math.cache' +For the Doxygen theme, this feature is builtin. Use either the ``@f[`` command +for block-level math or the ``@f$`` command for inline math. It's possible to +add extra CSS classes by placing ``@m_class`` in a paragraph before the actual +math block (or right before inline math), see the +`Doxygen theme-specific commands `_ +for more information. The :ini:`M_MATH_CACHE_FILE` option is supported as well; +there's no equivalent to the :ini:`M_MATH_RENDER_AS_CODE` option implemented at +this point. + In addition you need some LaTeX distribution installed. Use your distribution package manager, for example on Ubuntu: @@ -269,15 +279,25 @@ directive. `Code`_ ======= -Download the `m/code.py and ansilexer.py <{filename}/plugins.rst>`_ files, put -them including the ``m/`` directory into one of your :py:`PLUGIN_PATHS` and add -:py:`m.code` package to your :py:`PLUGINS` in ``pelicanconf.py``. This plugin -assumes presence of `m.htmlsanity <{filename}/plugins/htmlsanity.rst>`_. +For Pelican, download the `m/code.py and ansilexer.py <{filename}/plugins.rst>`_ +files, put them including the ``m/`` directory into one of your :py:`PLUGIN_PATHS` +and add :py:`m.code` 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'] +For the Doxygen theme, this feature is builtin. Use the ``@code{.ext}`` command +either in a block or inline, the various ``@include`` and ``@snippet`` commands +support it as well. Language detection is done from the value of ``.ext`` in +the ``@code`` command and from the include/snippet filename for the others. +It's possible to add extra CSS classes by placing ``@m_class`` in a paragraph +before the actual code block (or right before inline code), see the +`Doxygen theme-specific commands `_ +for more information. There's no possibility to highlight particular code +lines. + In addition you need to have `Pygments `_ installed. Get it via ``pip`` or your distribution package manager: diff --git a/doc/plugins/metadata.rst b/doc/plugins/metadata.rst index 54db3de6..59d19a8b 100644 --- a/doc/plugins/metadata.rst +++ b/doc/plugins/metadata.rst @@ -25,14 +25,14 @@ Metadata ######## -:breadcrumb: {filename}/plugins.rst Pelican plugins +:breadcrumb: {filename}/plugins.rst Plugins :summary: Assigns additional description and images to categories, authors and - tags. + tags in Pelican-powered sites. :footer: .. note-dim:: :class: m-text-center - `« Links and other <{filename}/plugins/links.rst>`_ | `Pelican plugins <{filename}/plugins.rst>`_ + `« Links and other <{filename}/plugins/links.rst>`_ | `Plugins <{filename}/plugins.rst>`_ .. role:: html(code) :language: html @@ -41,7 +41,9 @@ Metadata .. role:: rst(code) :language: rst -Assigns additional description and images to categories, authors and tags. +Assigns additional description and images to categories, authors and tags in +Pelican-powered sites. As it extends a Pelican-specific feature, it has no +equivalent for other themes. .. contents:: :class: m-block m-default @@ -72,8 +74,9 @@ directories are as follows and can be configured with these settings: The m.css Pelican theme recognizes presence of this plugin and renders the additional metadata both in the page and in the `Open Graph `_ -and `Twitter Card `_ social :html:`` tags, in addition to tags rendered by -`articles themselves <{filename}/pelican/theme.rst#social-meta-tags-for-articles>`_. +and `Twitter Card `_ +social :html:`` tags, in addition to tags rendered by +`articles themselves <{filename}/themes/pelican.rst#social-meta-tags-for-articles>`_. See below for more information. `Author metadata`_ @@ -115,7 +118,7 @@ following metadata are recognized: badge on articles, to author details on author page and in ``og:image`` / ``twitter:image`` social :html:`` tags on author page, overriding the global :py:`M_SOCIAL_IMAGE`. It's expected to be smaller and square - similarly to the :py:`M_SOCIAL_IMAGE` `described in the theme documentation <{filename}/pelican/theme.rst#global-site-image>`_. + similarly to the :py:`M_SOCIAL_IMAGE` `described in the theme documentation <{filename}/themes/pelican.rst#global-site-image>`_. If not set, the details and badges are rendered without images and no social tag is present. Does not affect ``twitter:card``, it's set to ``summary`` regardless of whether the image is present or not. @@ -188,11 +191,11 @@ for category named *Guest posts* will be in a file named being in given category. The m.css Pelican theme uses it to add an image to category badges on articles, to category details on category page and in ``og:image`` / ``twitter:image`` social :html:`` tags on category - page. If `article cover image <{filename}/pelican/theme.rst#jumbo-articles>`_ + page. If `article cover image <{filename}/themes/pelican.rst#jumbo-articles>`_ is not specified, the image is used also for ``og:image`` / ``twitter:image`` on given article, overriding the global :py:`M_SOCIAL_IMAGE`. It's expected to be smaller and square similarly to the - :py:`M_SOCIAL_IMAGE` `described in the theme documentation <{filename}/pelican/theme.rst#global-site-image>`_. + :py:`M_SOCIAL_IMAGE` `described in the theme documentation <{filename}/themes/pelican.rst#global-site-image>`_. If not set, the details and badges are rendered without images and no social tag is present. Does not affect ``twitter:card``, it's set to ``summary`` or ``summary_large_image`` depending only on presence of diff --git a/doc/plugins/plots-and-graphs-test.rst b/doc/plugins/plots-and-graphs-test.rst index eb5824d3..b25915ab 100644 --- a/doc/plugins/plots-and-graphs-test.rst +++ b/doc/plugins/plots-and-graphs-test.rst @@ -26,7 +26,7 @@ Test #### :save_as: plugins/plots-and-graphs/test/index.html -:breadcrumb: {filename}/plugins.rst Pelican plugins +:breadcrumb: {filename}/plugins.rst Plugins {filename}/plugins/plots-and-graphs.rst Plots and graphs Plots diff --git a/doc/plugins/plots-and-graphs.rst b/doc/plugins/plots-and-graphs.rst index a8520145..2c24482f 100644 --- a/doc/plugins/plots-and-graphs.rst +++ b/doc/plugins/plots-and-graphs.rst @@ -25,12 +25,12 @@ Plots and graphs ################ -:breadcrumb: {filename}/plugins.rst Pelican plugins +:breadcrumb: {filename}/plugins.rst Plugins :footer: .. note-dim:: :class: m-text-center - `« Math and code <{filename}/plugins/math-and-code.rst>`_ | `Pelican plugins <{filename}/plugins.rst>`_ | `Links and other » <{filename}/plugins/math-and-code.rst>`_ + `« Math and code <{filename}/plugins/math-and-code.rst>`_ | `Plugins <{filename}/plugins.rst>`_ | `Links and other » <{filename}/plugins/math-and-code.rst>`_ .. role:: dot(code) :language: dot @@ -57,15 +57,17 @@ the graphics is rendered to a SVG that's embedded directly in the HTML markup. `Plots`_ ======== -Download the `m/plots.py <{filename}/plugins.rst>`_ file, put it including the -``m/`` directory into one of your :py:`PLUGIN_PATHS` and add ``m.plots`` -package to your :py:`PLUGINS` in ``pelicanconf.py``. +For Pelican, download the `m/plots.py <{filename}/plugins.rst>`_ file, put it +including the ``m/`` directory into one of your :py:`PLUGIN_PATHS` and add +``m.plots`` package to your :py:`PLUGINS` in ``pelicanconf.py``. .. code:: python PLUGINS += ['m.plots'] M_PLOTS_FONT = 'Source Sans Pro' +This feature has no equivalent in the `Doxygen theme <{filename}/documentation/doxygen.rst>`_. + Set :py:`M_PLOTS_FONT` to a font that matches your CSS theme (it's Source Sans Pro for `builtin m.css themes <{filename}/css/themes.rst>`_), note that you *need to have the font installed* on your system, otherwise it will fall back @@ -170,9 +172,9 @@ comment :rst:`..`. `Graphs`_ ========= -Download the `m/dot.py <{filename}/plugins.rst>`_ file, put it including the -``m/`` directory into one of your :py:`PLUGIN_PATHS` and add ``m.dot`` -package to your :py:`PLUGINS` in ``pelicanconf.py``. +For Pelican, ownload the `m/dot.py <{filename}/plugins.rst>`_ file, put it +including the ``m/`` directory into one of your :py:`PLUGIN_PATHS` and add +``m.dot`` package to your :py:`PLUGINS` in ``pelicanconf.py``. .. note-danger:: @@ -190,7 +192,16 @@ theme (it's Source Sans Pro at :css:`16px` for `builtin m.css themes <{filename}/css/themes.rst>`_), note that you *need to have the font installed* on your system, otherwise it will fall back to whatever system font it finds instead (for example DejaVu Sans) and the output -won't look as expected. In addition you need the +won't look as expected. + +In case of Doxygen, this feature is builtin. Use the ``@dot`` and ``@dotfile`` +commands. It's possible to add extra CSS classes by placing ``@m_class`` in a +paragraph before the actual graph block, see the +`Doxygen theme-specific commands `_ +for more information. Font name and size is controlled using the builtin +:ini:`DOT_FONTNAME` and :ini:`DOT_FONTSIZE` options. + +In addition you need the `Graphviz `_ library installed. Get it via your distribution package manager, for example on Ubuntu: diff --git a/doc/themes.rst b/doc/themes.rst new file mode 100644 index 00000000..b62e6278 --- /dev/null +++ b/doc/themes.rst @@ -0,0 +1,58 @@ +.. + This file is part of m.css. + + Copyright © 2017, 2018, 2019 Vladimír VondruÅ¡ + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. +.. + +Themes +###### + +On top of the low-level CSS styles, m.css provides ready-made themes suited +mainly for static site generators and other tools powered by +`reStructuredText `_. + +.. note-warning:: + + Please, in this case, don't judge the book by its cover --- the + :abbr:`reST ` website might look like it was made in 1992 + and never updated since, but believe me, it's a remarkably designed format. + Once you dive into it, you will not want to go back to Markdown. + +.. button-success:: https://magnum.graphics + + Live demo + + magnum.graphics + +`Writing reST content » <{filename}/themes/writing-rst-content.rst>`_ +===================================================================== + +Quick guide and tips for writing content using :abbr:`reST `. +Chances are that you already know your way around from Sphinx or other +documentation tools, nevertheless there are some hidden tricks that you might +not know about yet. + +`Pelican theme » <{filename}/themes/pelican.rst>`_ +================================================== + +A feature-packed theme with modern and responsive design that exposes all of +m.css functionality with goodies on top such as social meta tags, breadcrumb +navigation and more. Used by this very website. diff --git a/doc/pelican/theme.rst b/doc/themes/pelican.rst similarity index 91% rename from doc/pelican/theme.rst rename to doc/themes/pelican.rst index ff37e68b..fbedcf2d 100644 --- a/doc/pelican/theme.rst +++ b/doc/themes/pelican.rst @@ -22,15 +22,18 @@ DEALINGS IN THE SOFTWARE. .. -Theme -##### +Pelican +####### -:breadcrumb: {filename}/pelican.rst Pelican +:alias: + /pelican/index.html + /pelican/theme/index.html +:breadcrumb: {filename}/themes.rst Themes :footer: .. note-dim:: :class: m-text-center - `« Writing content <{filename}/pelican/writing-content.rst>`_ | `Pelican <{filename}/pelican.rst>`_ + `« Writing reST content <{filename}/themes/writing-rst-content.rst>`_ | `Themes <{filename}/themes.rst>`_ .. role:: html(code) :language: html @@ -38,22 +41,97 @@ Theme :language: py .. role:: rst(code) :language: rst +.. role:: sh(code) + :language: sh .. |x| unicode:: U+00D7 .. nicer multiply sign -The second largest offering of m.css is a full-featured theme for the -`Pelican static site generator `_. The theme is -designed to fit both the use case of a simple blog consisting of just articles -or a full product/project/portfolio website where the blog is only a side dish. +`Pelican `_ is a static site generator powered by +Python and unlike most other static site generators, it uses +`reStructuredText `_ instead of +Markdown for authoring content. m.css provides a theme for it, together with a +set of useful plugins. The theme is designed to fit both the use case of a +simple blog consisting of just articles or a full product/project/portfolio +website where the blog is only a side dish. + +.. button-success:: https://magnum.graphics + + Live demo + + magnum.graphics .. contents:: :class: m-block m-default -`Quick start`_ -============== +`First steps with Pelican`_ +=========================== + +Install Pelican either via ``pip`` or using your system package manager. + +.. note-danger:: + + In order to use the m.css theme or `plugins <{filename}/plugins.rst>`_, you + need to install Pelican 4 and the Python 3 version of it. Most of the + plugins work with Python 3.4, while some (such as the + `math plugin <{filename}/plugins/math-and-code.rst#math>`_) need 3.5. + Python 2 is not supported and compatibility with Pelican 3.7 has been + dropped. + +.. code:: sh + + # You may need sudo here + pip3 install pelican + +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 + + mkdir ~/my-cool-site/ + cd ~/my-cool-site/ + pelican-quickstart + +This command will ask you a few questions. Leave most of the questions at their +defaults, you can change them later. Once the quickstart script finishes, you +can generate the website and spin up a auto-reload webserver for it with the +following command: + +.. code:: sh + + pelican -Dlr + +It will print quite some output about processing things and serving the data to +the console. Open your fresh website at http://localhost:8000. The site is now +empty, so let's create a simple article and put it into ``content/`` +subdirectory with a ``.rst`` extension. For this example that would be +``~/my-cool-site/content/my-cool-article.rst``: + +.. code:: rst + + My cool article + ############### + + :date: 2017-09-14 23:04 + :category: Cool things + :tags: cool, article, mine + :summary: This article has a cool summary. + + This article has not only cool summary, but also has cool contents. Lorem? + *Ipsum.* `Hi, google! `_ + +If you did everything right, the auto-reload script should pick the file up and +process it (check the console output). Then it's just a matter of refreshing +your browser to see it on the page. + +*That's it!* Congratulations, you successfully made your first steps with +Pelican. Well, apart from the fact that the default theme is a bit +underwhelming --- so let's fix that. + +`Basic theme setup`_ +==================== -Following the `Pelican quick start guide <{filename}/pelican.rst#quick-start>`_, -it's assumed you already have at least Python 3.4 and the Python 3 version of -Pelican installed. The easiest way to start is putting the +The easiest way to start is putting the :gh:`whole Git repository ` of m.css into your project, for example as a submodule: diff --git a/doc/pelican/writing-content.rst b/doc/themes/writing-rst-content.rst similarity index 96% rename from doc/pelican/writing-content.rst rename to doc/themes/writing-rst-content.rst index d8385662..f0111c08 100644 --- a/doc/pelican/writing-content.rst +++ b/doc/themes/writing-rst-content.rst @@ -22,15 +22,16 @@ DEALINGS IN THE SOFTWARE. .. -Writing content -############### +Writing reST content +#################### -:breadcrumb: {filename}/pelican.rst Pelican +:alias: /pelican/writing-content/index.html +:breadcrumb: {filename}/themes.rst Themes :footer: .. note-dim:: :class: m-text-center - `Pelican <{filename}/pelican.rst>`_ | `Theme » <{filename}/pelican/theme.rst>`_ + `Themes <{filename}/themes.rst>`_ | `Pelican » <{filename}/themes/pelican.rst>`_ .. role:: html(code) :language: html @@ -142,7 +143,7 @@ contents. Consecutive indented lines are treated as part of the same field. See the `Pelican documentation `_ for details about recognized fields and how various metadata can be also automatically extracted from the filesystem. The -`m.css Pelican theme <{filename}/pelican/theme.rst>`_ recognizes a few more +`m.css Pelican theme <{filename}/themes/pelican.rst>`_ recognizes a few more fields. `Directives`_ @@ -217,7 +218,7 @@ Example and corresponding output, note the indentation: .. note-info:: Please note that the above example code uses some directives provided by - `m.css Pelican plugins <{filename}/plugins.rst>`_ that are not builtin in + `m.css reST plugins <{filename}/plugins.rst>`_ that are not builtin in the :abbr:`reST ` parser itself. `Interpreted text roles`_ @@ -447,7 +448,7 @@ info about `inline markup `_ that do it better than the builtin +`various plugins <{filename}/plugins.rst>`_ that do it better than the builtin way. Head over to the official :abbr:`reST ` documentation for `more info about builtin directives `_. @@ -461,7 +462,7 @@ for `more info about builtin directives `__ role. -Again, m.css provides `Pelican plugins`_ that allow you to have inline code, -math, GitHub and Doxygen links and much more. Head over to the official +Again, m.css provides `various plugins`_ that allow you to have inline +code, math, GitHub and Doxygen links and much more. Head over to the official :abbr:`reST ` documentation for `more info about builtin roles `_. diff --git a/doc/why.rst b/doc/why.rst index 99367ca2..df599a94 100644 --- a/doc/why.rst +++ b/doc/why.rst @@ -83,10 +83,11 @@ If you are like me, you want a website that presents your main work, not that your main work is presenting websites. So remove the unneeded hassle of paying extra for a dynamic webhosting, installing and maintaining a huge CMS and patching it twice a month for a neverending stream new CVEs. Together with -`Pelican <{filename}/pelican.rst>`_, m.css provides a solution harnessing the -endless possibilities of your local machine to generate a bunch of static HTML -files, which you can then upload *anywhere*. And as a bonus, you have the full -control over your content --- nothing's hidden in opaque databases. +`Pelican <{filename}/themes/pelican.rst>`_, m.css provides a solution +harnessing the endless possibilities of your local machine to generate a bunch +of static HTML files, which you can then upload *anywhere*. And as a bonus, you +have the full control over your content --- nothing's hidden in opaque +databases. .. note-success:: diff --git a/documentation/test_doxygen/__init__.py b/documentation/test_doxygen/__init__.py index 0d298d22..24fd4948 100644 --- a/documentation/test_doxygen/__init__.py +++ b/documentation/test_doxygen/__init__.py @@ -26,7 +26,6 @@ import os import shutil import subprocess import unittest -import xml.etree.ElementTree as ET from doxygen import run, default_templates, default_wildcard, default_index_pages diff --git a/site/pelicanconf.py b/site/pelicanconf.py index 7f04af2b..1bf59d39 100644 --- a/site/pelicanconf.py +++ b/site/pelicanconf.py @@ -78,11 +78,13 @@ M_LINKS_NAVBAR1 = [('Why?', 'why/', 'why', []), ('Components', 'css/components/', 'css/components'), ('Page layout', 'css/page-layout/', 'css/page-layout'), ('Themes', 'css/themes/', 'css/themes')]), - ('Pelican', 'pelican/', 'pelican', [ - ('Writing content', 'pelican/writing-content/', 'pelican/writing-content'), - ('Theme', 'pelican/theme/', 'pelican/theme')])] + ('Themes', 'themes/', 'themes', [ + ('Writing reST content', 'themes/writing-rst-content/', 'pelican/writing-content'), + ('Pelican', 'themes/pelican/', 'themes/pelican')])] -M_LINKS_NAVBAR2 = [('Plugins', 'plugins/', 'plugins', [ +M_LINKS_NAVBAR2 = [('Doc generators', 'documentation/', 'documentation', [ + ('Doxygen C++ theme', 'documentation/doxygen/', 'documentation/doxygen')]), + ('Plugins', 'plugins/', 'plugins', [ ('HTML sanity', 'plugins/htmlsanity/', 'plugins/htmlsanity'), ('Components', 'plugins/components/', 'plugins/components'), ('Images', 'plugins/images/', 'plugins/images'), @@ -90,7 +92,6 @@ M_LINKS_NAVBAR2 = [('Plugins', 'plugins/', 'plugins', [ ('Links and other', 'plugins/links/', 'plugins/links'), ('Plots and graphs', 'plugins/plots-and-graphs/', 'plugins/plots-and-graphs'), ('Metadata', 'plugins/metadata/', 'plugins/metadata')]), - ('Doxygen theme', 'doxygen/', 'doxygen', []), ('GitHub', 'https://github.com/mosra/m.css', '', [])] M_LINKS_FOOTER1 = [('m.css', '/'), @@ -108,11 +109,12 @@ M_LINKS_FOOTER2 = [('CSS', 'css/'), ('Page layout', 'css/page-layout/'), ('Themes', 'css/themes/')] -M_LINKS_FOOTER3 = [('Pelican', 'pelican/'), - ('Writing content', 'pelican/writing-content/'), - ('Theme', 'pelican/theme/'), +M_LINKS_FOOTER3 = [('Themes', 'themes/'), + ('Writing reST content', 'themes/writing-rst-content/'), + ('Pelican', 'themes/pelican/'), ('', ''), - ('Doxygen theme', 'doxygen/')] + ('Doc generators', 'documentation/'), + ('Doxygen C++ theme', 'documentation/doxygen/')] M_LINKS_FOOTER4 = [('Plugins', 'plugins/'), ('HTML sanity', 'plugins/htmlsanity/'), @@ -138,6 +140,7 @@ EXTRA_PATH_METADATA = {'static/favicon.ico': {'path': 'favicon.ico'}} PLUGIN_PATHS = ['../plugins'] PLUGINS = ['m.abbr', + 'm.alias', 'm.code', 'm.components', 'm.dox', -- 2.30.2