https://cylc.github.io/cylc-sphinx-extensions/

Sphinx extensions for documenting Cylc projects.
https://cylc.github.io/cylc-sphinx-extensions/

cylc sphinx

Last synced: 5 days ago
JSON representation

Sphinx extensions for documenting Cylc projects.

• Host: GitHub
• URL: https://cylc.github.io/cylc-sphinx-extensions/
• Owner: cylc
• License: gpl-3.0
• Created: 2019-07-30T09:47:14.000Z (over 5 years ago)
• Default Branch: master
• Last Pushed: 2024-09-26T12:07:52.000Z (about 2 months ago)
• Last Synced: 2024-11-07T11:18:21.148Z (7 days ago)
• Topics: cylc, sphinx
• Language: Python
• Homepage: https://cylc.github.io/cylc-sphinx-extensions/
• Size: 6.51 MB
• Stars: 4
• Watchers: 7
• Forks: 8
• Open Issues: 10
• Metadata Files:
  • Readme: README.rst
  • Contributing: CONTRIBUTING.md
  • License: LICENSE

Awesome Lists containing this project

README

        
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   # 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-2024 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/.