cylc-sphinx-extensions


Namecylc-sphinx-extensions JSON
Version 1.4.2 PyPI version JSON
download
home_page
SummarySphinx extensions for documenting Cylc
upload_time2023-04-17 09:46:10
maintainer
docs_urlNone
author
requires_python
licenseGPL
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            Cylc Sphinx Extensions
======================

A library of Sphinx extensions for documenting Cylc projects.


Installation
------------

Install all extensions (but not dependencies)::

   $ pip install cylc-sphinx-extensions

OR all extensions + dependencies for specified extension(s) by name::

   $ pip install cylc-sphinx-extensions.git[cylc_lang]

OR all extensions + dependencies for all extensions::

   $ pip install cylc-sphinx-extensions.git[all]

Note the ``minicylc`` extension requires ``graphviz``::

   # install graphviz from your package manager e.g:
   $ sudo apt-get install -y graphviz


Usage
-----

To use an extension register it in your project's ``conf.py`` e.g::

   extension = [
       'cylc.sphinx_ext.cylc_lang'
   ]

Some of these extensions are "auto-loading" and do not require any extra steps
to activate.

If the ``html_static_path`` configuration is set in your ``conf.py`` you will
need to move this into a ``setup`` function, otherwise extensions cannot append
to this path to add their own static resources e.g::

   def setup(app):
       app.config.html_static_path.append('_static')


Development
-----------

Fork and clone ``https://github.com/cylc/cylc-sphinx-extensions.git``.

Extensions are auto-documented from their module docstrings.

Build documentation by running::

   $ make clean <format>  # e.g. make html slides

This documentation build serves as a simple test battery (warnings will cause
it to fail), for everything else there's pytest::

   $ pytest

For code linting::

   $ pycodestyle .  # python
   $ eslint cylc/   # javascript


Copyright and Terms of Use
--------------------------

Copyright (C) 2008-2023 NIWA & British Crown (Met Office) & Contributors.

Cylc is free software: you can redistribute it and/or modify it under the terms
of the GNU General Public License as published by the Free Software Foundation,
either version 3 of the License, or (at your option) any later version.

Cylc is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
Cylc.  If not, see GNU licenses http://www.gnu.org/licenses/.

            

Raw data

            {
    "_id": null,
    "home_page": "",
    "name": "cylc-sphinx-extensions",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "",
    "author": "",
    "author_email": "",
    "download_url": "https://files.pythonhosted.org/packages/fd/d6/6e7dab6de7d7e10f63f8bee1485a66bb76774d0e777869b479cea3f65d7a/cylc-sphinx-extensions-1.4.2.tar.gz",
    "platform": null,
    "description": "Cylc Sphinx Extensions\n======================\n\nA library of Sphinx extensions for documenting Cylc projects.\n\n\nInstallation\n------------\n\nInstall all extensions (but not dependencies)::\n\n   $ pip install cylc-sphinx-extensions\n\nOR all extensions + dependencies for specified extension(s) by name::\n\n   $ pip install cylc-sphinx-extensions.git[cylc_lang]\n\nOR all extensions + dependencies for all extensions::\n\n   $ pip install cylc-sphinx-extensions.git[all]\n\nNote the ``minicylc`` extension requires ``graphviz``::\n\n   # install graphviz from your package manager e.g:\n   $ sudo apt-get install -y graphviz\n\n\nUsage\n-----\n\nTo use an extension register it in your project's ``conf.py`` e.g::\n\n   extension = [\n       'cylc.sphinx_ext.cylc_lang'\n   ]\n\nSome of these extensions are \"auto-loading\" and do not require any extra steps\nto activate.\n\nIf the ``html_static_path`` configuration is set in your ``conf.py`` you will\nneed to move this into a ``setup`` function, otherwise extensions cannot append\nto this path to add their own static resources e.g::\n\n   def setup(app):\n       app.config.html_static_path.append('_static')\n\n\nDevelopment\n-----------\n\nFork and clone ``https://github.com/cylc/cylc-sphinx-extensions.git``.\n\nExtensions are auto-documented from their module docstrings.\n\nBuild documentation by running::\n\n   $ make clean <format>  # e.g. make html slides\n\nThis documentation build serves as a simple test battery (warnings will cause\nit to fail), for everything else there's pytest::\n\n   $ pytest\n\nFor code linting::\n\n   $ pycodestyle .  # python\n   $ eslint cylc/   # javascript\n\n\nCopyright and Terms of Use\n--------------------------\n\nCopyright (C) 2008-2023 NIWA & British Crown (Met Office) & Contributors.\n\nCylc is free software: you can redistribute it and/or modify it under the terms\nof the GNU General Public License as published by the Free Software Foundation,\neither version 3 of the License, or (at your option) any later version.\n\nCylc is distributed in the hope that it will be useful, but WITHOUT ANY\nWARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A\nPARTICULAR PURPOSE.  See the GNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License along with\nCylc.  If not, see GNU licenses http://www.gnu.org/licenses/.\n",
    "bugtrack_url": null,
    "license": "GPL",
    "summary": "Sphinx extensions for documenting Cylc",
    "version": "1.4.2",
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "23f0f713c8ef1765ce997f8e52c58e8be4eea1c4725c19d4f8a76536e9722cad",
                "md5": "ae69cef3ea27984acf122bc9eefcf18e",
                "sha256": "944564cf8cb9ef1d4fff52eae40019d0bed882dafc10f988f9e6c95ab6b7af8b"
            },
            "downloads": -1,
            "filename": "cylc_sphinx_extensions-1.4.2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "ae69cef3ea27984acf122bc9eefcf18e",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 47837,
            "upload_time": "2023-04-17T09:46:08",
            "upload_time_iso_8601": "2023-04-17T09:46:08.953658Z",
            "url": "https://files.pythonhosted.org/packages/23/f0/f713c8ef1765ce997f8e52c58e8be4eea1c4725c19d4f8a76536e9722cad/cylc_sphinx_extensions-1.4.2-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "fdd66e7dab6de7d7e10f63f8bee1485a66bb76774d0e777869b479cea3f65d7a",
                "md5": "ffac706594e48def630600b6b721628d",
                "sha256": "578ba6a36adc76598fb630423cad1992abfc168ff8d9e414dc44dde7983d3db1"
            },
            "downloads": -1,
            "filename": "cylc-sphinx-extensions-1.4.2.tar.gz",
            "has_sig": false,
            "md5_digest": "ffac706594e48def630600b6b721628d",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 31439,
            "upload_time": "2023-04-17T09:46:10",
            "upload_time_iso_8601": "2023-04-17T09:46:10.800485Z",
            "url": "https://files.pythonhosted.org/packages/fd/d6/6e7dab6de7d7e10f63f8bee1485a66bb76774d0e777869b479cea3f65d7a/cylc-sphinx-extensions-1.4.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-04-17 09:46:10",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "lcname": "cylc-sphinx-extensions"
}
        
Elapsed time: 0.05611s