Skip to content

Instantly share code, notes, and snippets.

@shidarin

shidarin/sphinx_style_tests.rst

Last active August 29, 2015 14:03
Show Gist options
  • Save shidarin/b63eebc49c62ec9e19fd to your computer and use it in GitHub Desktop.
Save shidarin/b63eebc49c62ec9e19fd to your computer and use it in GitHub Desktop.
Download ZIP
Sphinx Style Test Page - Rst for testing a whole bunch of Sphinx styles. Useful for developing convertors.
Raw
sphinx_style_tests.rst

Testing

This rst file is for testing the various Sphinx styles and class conversions that we'll find in a Sphinx rst file. Ideally we want to run through everything pretty often.

The first tests

Code

Here we're going to test some code blocks.

import os
from xml.etree import ElementTree

class AscDescBase(object):  # pylint: disable=R0903
    """Base class for most Asc XML type nodes, allows for infinite desc

    Description
    ~~~~~~~~~~~

    This class is meant to be inherited by any node type that uses description
    fields.

    **Attributes:**

        desc : [str]
            Since all Asc nodes which can contain a single description, can
            actually contain an infinite number of descriptions, the desc
            attribute is a list, allowing us to store every single description
            found during parsing.

            Setting desc directly will cause the value given to append to the
            end of the list, but desc can also be replaced by passing it a list
            or tuple. Desc can be emptied by passing it None, [] or ().

    **Public Methods:**

        parse_xml_descs()
            Parses an ElementTree Element for any Description tags and appends
            any text they contain to the ``desc``.

    """
    def __init__(self):
        super(AscDescBase, self).__init__()
        self._desc = []

    # Properties ==============================================================

    @property
    def desc(self):
        """Returns the list of descriptions"""
        return self._desc

    @desc.setter
    def desc(self, value):
        """Adds an entry to the descriptions"""
        if value is None:
            self._desc = []
        elif type(value) in [list, tuple]:
            self._desc = list(value)
        else:
            self._desc.append(value)

    # Public Methods ==========================================================

    def parse_xml_descs(self, xml_element):
        """Parses an ElementTree element to find & add any descriptions

        **Args:**
            xml_element : (``xml.etree.ElementTree.Element``)
                The element to parse for Description elements. Any found
                will be appended to the end of ``desc``

        **Returns:**
            None

        **Raises:**
            None

        """
        for desc_entry in xml_element.findall('Description'):
            if desc_entry.text:  # Don't attend if text returns none
                self.desc.append(desc_entry.text)

Wow wasn't that a great code block! How about some console stuff now.

$ ls
art         modules         octopress       thorium
$ cd modules/
$ ls
animatedSnap3D      cardToTrack     iconPanel       viewerSync
$ cd animatedSnap3D/
$ tree
.
├── LICENSE
├── MANIFEST.in
├── README.rst
├── animatedSnap3D
│   ├── __init__.py
│   └── animatedSnap3D.py
└── setup.py

1 directory, 6 files

Wow that was some more great code.

Line Numbered Code

Let's try some basic line numbered code.

if type(value) is float:
    # Rather than mess about with float -> Decimal conversion,
    # it suits our accuracy needs just fine to go straight to string.
    value = str(value)
elif type(value) is int:
    # If we're giving an int, we need to add a '.0' behind it.
    value = str(value) + '.0'
elif type(value) is Decimal:
    return value
elif type(value) is str:
    if '.' not in value:
        value += '.0'

Marked Code

Now we're mark the code.

if type(value) is float:
    # Rather than mess about with float -> Decimal conversion,
    # it suits our accuracy needs just fine to go straight to string.
    value = str(value)
elif type(value) is int:
    # If we're giving an int, we need to add a '.0' behind it.
    value = str(value) + '.0'
elif type(value) is Decimal:
    return value
elif type(value) is str:
    if '.' not in value:
        value += '.0'

Cross Referencing Python Objects

:py:mod:`cdl_convert`

:py:func:`cdl_convert.main`

:py:data:`cdl_convert.__author__`

:py:const:`cdl_convert.__credits__`

:py:class:`cdl_convert.base.AscDescBase`

:py:meth:`cdl_convert.base.AscDescBase.parse_xml_descs`

:py:attr:`cdl_convert.base.AscDescBase.desc`

:py:exc:`TypeError`

:py:obj:`cdl_convert.banana`

More Tests!

Even more tests now.

Paragraph Level Markup

My favorite!

Note

This stuff is important.

I'm not kidding, it's critical.

Some great warnings coming up.

Warning

Pay head to this warning, it could save your life.

Or it could kill you even.

Versions

.. versionadded:: 6.7.4.3
    The ability to kill people with warnings.

    More things `added`:
        - Things
        - More things
        - Even more things.

Holy cow! what a list.

.. versionchanged:: 1.5
    Things got shifted around, and removed.

    Removing `things` was important.


.. deprecated:: 6.4
    Hey don't use this `anymore`

    Or if you do, don't use it a lot.

Paragraph Level Markup With Code

My favorite!

Note

This stuff is important.

I'm not kidding, it's critical.

if type(value) is float:
    # Rather than mess about with float -> Decimal conversion,
    # it suits our accuracy needs just fine to go straight to string.
    value = str(value)
elif type(value) is int:
    # If we're giving an int, we need to add a '.0' behind it.
    value = str(value) + '.0'
elif type(value) is Decimal:
    return value
elif type(value) is str:
    if '.' not in value:
        value += '.0'

Some great warnings coming up.

Warning

Pay head to this warning, it could save your life.

if type(value) is float:
    # Rather than mess about with float -> Decimal conversion,
    # it suits our accuracy needs just fine to go straight to string.
    value = str(value)
elif type(value) is int:
    # If we're giving an int, we need to add a '.0' behind it.
    value = str(value) + '.0'
elif type(value) is Decimal:
    return value
elif type(value) is str:
    if '.' not in value:
        value += '.0'

Or it could kill you even.

Versions with Code

.. versionadded:: 6.7.4.3
    The ability to kill people with warnings.

    More things `added`:
        - Things
        - More things
        - Even more things.

    .. code-block:: python
        :linenos:
        :emphasize-lines: 3,5

        if type(value) is float:
            # Rather than mess about with float -> Decimal conversion,
            # it suits our accuracy needs just fine to go straight to string.
            value = str(value)
        elif type(value) is int:
            # If we're giving an int, we need to add a '.0' behind it.
            value = str(value) + '.0'
        elif type(value) is Decimal:
            return value
        elif type(value) is str:
            if '.' not in value:
                value += '.0'

Holy cow! what a list.

.. versionchanged:: 1.5
    Things got shifted around, and removed.

    Removing `things` was important.

    .. code-block:: python
        :linenos:
        :emphasize-lines: 3,5

        if type(value) is float:
            # Rather than mess about with float -> Decimal conversion,
            # it suits our accuracy needs just fine to go straight to string.
            value = str(value)
        elif type(value) is int:
            # If we're giving an int, we need to add a '.0' behind it.
            value = str(value) + '.0'
        elif type(value) is Decimal:
            return value
        elif type(value) is str:
            if '.' not in value:
                value += '.0'


.. deprecated:: 6.4
    Hey don't use this `anymore`

    .. code-block:: python
        :linenos:
        :emphasize-lines: 3,5

        if type(value) is float:
            # Rather than mess about with float -> Decimal conversion,
            # it suits our accuracy needs just fine to go straight to string.
            value = str(value)
        elif type(value) is int:
            # If we're giving an int, we need to add a '.0' behind it.
            value = str(value) + '.0'
        elif type(value) is Decimal:
            return value
        elif type(value) is str:
            if '.' not in value:
                value += '.0'

    Or if you do, don't use it a lot.

Other

.. seealso::

   Module :py:mod:`zipfile`
      Documentation of the :py:mod:`zipfile` standard module.

   `GNU tar manual, Basic Tar Format <http://link>`_
      Documentation for tar archive files, including GNU tar extensions.

Last Tests

AUTODOCS, ENGAGE

Autodoc Stuff

cdl_convert

.. automodule:: cdl_convert

Wow what a great module.

ColorCollection

.. autoclass:: cdl_convert.collection.ColorCollection

I've seen better.

ValueError

.. autoexception:: ValueError

to_decimal

.. autofunction:: cdl_convert.utils.to_decimal

__url__

.. autodata:: cdl_convert.__url__

append_child

.. automethod:: cdl_convert.collection.ColorCollection.append_child

xml attribute

.. autoattribute:: cdl_convert.collection.ColorCollection.xml
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment