Documentation tutorial¶

Sphinx logo

long_description=long_description,
+   long_description_content_type="text/markdown",

$ pip install -U setuptools

Anne Gentle <annegentle@gmail.com>
à:   write-the-docs@googlegroups.com
date:        7 août 2013 16:50
objet:       Re: Resources for writing good documentation

Hey all,

Looks like I am going to be giving a beginners presentation about writing
docs at the PDX Python user group.
I am adding a resource section that will list good places to go to look for
information about writing docs. My current list contains:

* http://producingoss.com/en/getting-started.html
* http://docs.writethedocs.org/

What are some other good documentation resources that I might be missing ?
I hope to add all of the content from this talk back into docs.writethedocs.org,
so that it will live on.

- :ref:`github_fork_and_edit_button`
- https://github.com/blog/844-forking-with-the-edit-button
- https://confluence.atlassian.com/display/BITBUCKET/Fork+a+Repo,+Compare+Code,+and+Create+a+Pull+Request

johnKitchin07 <johnrkitchin@gmail.com>
répondre à  sphinx-dev@googlegroups.com
à   sphinx-dev <sphinx-dev@googlegroups.com>
date    17 mars 2011 14:11
objet   [sphinx-dev] Re: Wiki based on Sphinx
liste de diffusion  <sphinx-dev.googlegroups.com> Filtrer les messages de cette liste de diffusion

language = "es"

language = "ca"

# Add file patterns to exclude from build
exclude_patterns = []

# Add file patterns to exclude from build
exclude_patterns = ["drafts/*"]

if conf_product==’mini’:
        exclude_patterns = ['interface/*.rst',’dialogs/*.rst’]
elif conf_product==’main’:
        exclude_patterns = ['mini-indexes.rst]

- https://gitlab.com/gdevops/tuto_documentation/blob/master/conf.py

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
#
# Configuration file for the Sphinx documentation builder.
# http://www.sphinx-doc.org/en/stable/config

from datetime import datetime

project = "Tuto Documentation"
author = "DevOps people"
version = "0.1.0"
release = version
now = datetime.now()
today = f"{now.year}-{now.month:02}-{now.day:02} {now.hour:02}H{now.minute:02}"
copyright = f"2009-{now.year}, {author}"
source_suffix = {
    ".rst": "restructuredtext",
    ".md": "markdown",
}
master_doc = "index"
language = None
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".venv"]
html_theme = "bizstyle"
pygments_style = "sphinx"
extensions = ["sphinx.ext.intersphinx", "recommonmark", "sphinx_tabs.tabs"]
intersphinx_mapping = {
    "python": ("https://docs.python.org/", None),
    "official_sphinx": ("http://www.sphinx-doc.org/", None),
    "https://gdevops.gitlab.io/tuto_python/": None,
    "https://gdevops.gitlab.io/tuto_django/": None,
    "docker": ("https://gdevops.gitlab.io/tuto_docker/", None),
    "https://gdevops.gitlab.io/tuto_cli/": None,
    "https://gdevops.gitlab.io/tuto_build/": None,
    "https://gdevops.gitlab.io/tuto_kubernetes/": None,
    "http://blockdiag.com/en/": None,
}
extensions = extensions + ["sphinx.ext.todo"]
todo_include_todos = True




###########################################################################
#          auto-created readthedocs.org specific configuration            #
###########################################################################


#
# The following code was added during an automated build on readthedocs.org
# It is auto created and injected for every build. The result is based on the
# conf.py.tmpl file found in the readthedocs.org codebase:
# https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl
#


import importlib
import sys
import os.path
from six import string_types

from sphinx import version_info

# Get suffix for proper linking to GitHub
# This is deprecated in Sphinx 1.3+,
# as each page can have its own suffix
if globals().get('source_suffix', False):
    if isinstance(source_suffix, string_types):
        SUFFIX = source_suffix
    elif isinstance(source_suffix, (list, tuple)):
        # Sphinx >= 1.3 supports list/tuple to define multiple suffixes
        SUFFIX = source_suffix[0]
    elif isinstance(source_suffix, dict):
        # Sphinx >= 1.8 supports a mapping dictionary for multiple suffixes
        SUFFIX = list(source_suffix.keys())[0]  # make a ``list()`` for py2/py3 compatibility
    else:
        # default to .rst
        SUFFIX = '.rst'
else:
    SUFFIX = '.rst'

# Add RTD Static Path. Add to the end because it overwrites previous files.
if not 'html_static_path' in globals():
    html_static_path = []
if os.path.exists('_static'):
    html_static_path.append('_static')

# Add RTD Theme only if they aren't overriding it already
using_rtd_theme = (
    (
        'html_theme' in globals() and
        html_theme in ['default'] and
        # Allow people to bail with a hack of having an html_style
        'html_style' not in globals()
    ) or 'html_theme' not in globals()
)
if using_rtd_theme:
    theme = importlib.import_module('sphinx_rtd_theme')
    html_theme = 'sphinx_rtd_theme'
    html_style = None
    html_theme_options = {}
    if 'html_theme_path' in globals():
        html_theme_path.append(theme.get_html_theme_path())
    else:
        html_theme_path = [theme.get_html_theme_path()]

if globals().get('websupport2_base_url', False):
    websupport2_base_url = 'https://readthedocs.org/websupport'
    websupport2_static_url = 'https://assets.readthedocs.org/static/'


#Add project information to the template context.
context = {
    'using_theme': using_rtd_theme,
    'html_theme': html_theme,
    'current_version': "latest",
    'version_slug': "latest",
    'MEDIA_URL': "https://media.readthedocs.org/",
    'STATIC_URL': "https://assets.readthedocs.org/static/",
    'PRODUCTION_DOMAIN': "readthedocs.org",
    'versions': [
    ("latest", "/en/latest/"),
    ("stable", "/en/stable/"),
    ("0.3.0", "/en/0.3.0/"),
    ("0.1.0", "/en/0.1.0/"),
    ],
    'downloads': [ 
    ("pdf", "//devopstutodoc.readthedocs.io/_/downloads/en/latest/pdf/"),
    ("html", "//devopstutodoc.readthedocs.io/_/downloads/en/latest/htmlzip/"),
    ],
    'subprojects': [ 
    ],
    'slug': 'devopstutodoc',
    'name': u'devopstuto_doc',
    'rtd_language': u'en',
    'programming_language': u'py',
    'canonical_url': 'https://devopstutodoc.readthedocs.io/en/latest/',
    'analytics_code': '',
    'single_version': False,
    'conf_py_path': '/',
    'api_host': 'https://readthedocs.org',
    'github_user': 'None',
    'github_repo': 'None',
    'github_version': 'master',
    'display_github': False,
    'bitbucket_user': 'None',
    'bitbucket_repo': 'None',
    'bitbucket_version': 'master',
    'display_bitbucket': False,
    'gitlab_user': 'gdevops',
    'gitlab_repo': 'tuto_documentation',
    'gitlab_version': 'master',
    'display_gitlab': True,
    'READTHEDOCS': True,
    'using_theme': (html_theme == "default"),
    'new_theme': (html_theme == "sphinx_rtd_theme"),
    'source_suffix': SUFFIX,
    'ad_free': False,
    'user_analytics_code': '',
    'global_analytics_code': 'UA-17997319-1',
    'commit': '79bea070',
}




if 'html_context' in globals():
    
    html_context.update(context)
    
else:
    html_context = context

# Add custom RTD extension
if 'extensions' in globals():
    # Insert at the beginning because it can interfere
    # with other extensions.
    # See https://github.com/rtfd/readthedocs.org/pull/4054
    extensions.insert(0, "readthedocs_ext.readthedocs")
else:
    extensions = ["readthedocs_ext.readthedocs"]

# Add External version warning banner to the external version documentation
if 'branch' == 'external':
    extensions.insert(1, "readthedocs_ext.external_version_warning")

project_language = 'en'

# User's Sphinx configurations
language_user = globals().get('language', None)
latex_engine_user = globals().get('latex_engine', None)
latex_elements_user = globals().get('latex_elements', None)

# Remove this once xindy gets installed in Docker image and XINDYOPS
# env variable is supported
# https://github.com/rtfd/readthedocs-docker-images/pull/98
latex_use_xindy = False

chinese = any([
    language_user in ('zh_CN', 'zh_TW'),
    project_language in ('zh_CN', 'zh_TW'),
])

japanese = any([
    language_user == 'ja',
    project_language == 'ja',
])

if chinese:
    latex_engine = latex_engine_user or 'xelatex'

    latex_elements_rtd = {
        'preamble': '\\usepackage[UTF8]{ctex}\n',
    }
    latex_elements = latex_elements_user or latex_elements_rtd
elif japanese:
    latex_engine = latex_engine_user or 'platex'

:abbr:`LIFO (last-in, first-out)`.

For example, if the reference :doc:`command` occurs in the document inline/index,
then the link refers to :file:`inline/command`.

reference is :doc:`Index principal </index>` or :doc:`Index local <../markup>`

reference is :doc:`../markup`

The name of an OS-level command, such as :command:`rm`.

See :download:`this example script <../example.py>`.

.. glossary::

   environment
      A structure where information about all documents under the root is
      saved, and used for cross-referencing.  The environment is pickled
      after the parsing stage, so that successive runs only need to read
      and parse new and changed documents.

   source directory
      The directory which, including its subdirectories, contains all
      source files for one Sphinx project.

.. glossary::

   term 1
   term 2
      Definition of both terms.

button :guilabel:`Start`

button :guilabel:`&Start`

:menuselection:`Start --> Programs`

:menuselection:`Start --> &Programs`

:program:`Geany.exe`

.. index::
   single: execution; context
   module: __main__
   module: sys
   triple: module; search; path

The execution context
---------------------

...

   .. index:: Python

and one page contains ::

   .. index:: ! Python

then the backlink to the latter page is emphasized among the three backlinks.

For index directives containing only "single" entries, there is a shorthand
notation::

   .. index:: BNF, grammar, syntax, notation

This creates four index entries.

.. versionchanged:: 1.1
   Added ``see`` and ``seealso`` types, as well as marking main entries.

.. only:: html and draft

# tags.add('student')
# tags.add('stagiaire')
tags.add('prof')

.. only prof

    Solution du problème

.. index::
   pair: sphinx ; pair
   pair: sphinx important; contents

.. contents::
   :local:

.. contents::
   :depth: 2

.. deprecated:: 3.1
   Use :func:`spam` instead.

.. hlist::
   :columns: 3

   * A list of
   * short items
   * that should be
   * displayed
   * horizontally

.. note::

   This function is not suitable for sending spam e-mails.

.. versionadded:: 2.5
   The *spam* parameter.

.. default-domain:: name

.. default-domain:: C

.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

.. c:member:: PyObject* PyTypeObject.tp_bases

.. rst:directive:: .. c:macro:: name

.. rst:directive:: .. c:type:: name

.. c:var:: PyObject* PyClass_Type

.. rst:role:: c:data

.. rst:role:: c:func

.. rst:role:: c:macro

.. rst:role:: c:type

.. cpp:function:: bool namespaced::theclass::method(int arg1, std::string arg2)

   Describes a method with parameters and types.

.. cpp:function:: bool namespaced::theclass::method(arg1, arg2)

   Describes a method without types.

.. cpp:function:: const T &array<T>::operator[]() const

   Describes the constant indexing operator of a templated array.

.. cpp:function:: operator bool() const

   Describe a casting operator here.

.. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept

   Describe a constexpr function here.

.. cpp:member:: std::string theclass::name

.. cpp:member:: std::string theclass::name[N][M]

.. cpp:type:: theclass::const_iterator

.. literalinclude:: example.py

.. literalinclude:: example.rb
   :language: ruby
   :linenos:

15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
"""Returns a table of file names with the following informations

"""

__author__ = "Patrick Vergain <pvergain@gmail.com>"


import hashlib
import logging
import zlib

from unipath import Path


log = logging.getLogger("get_table_hash")


class crc32(object):
    """hashlib-compatible interface for CRC-32 support

    http://stackoverflow.com/questions/1742866/compute-crc-of-file-in-python
    """

    name = "crc32"
    digest_size = 4
    block_size = 1

    def __init__(self, arg=""):
        self.__digest = 0
        self.update(arg)

    def copy(self):
        copy = super(self.__class__, self).__new__(__class__)
        copy.__digest = self.__digest
        return copy

    def digest(self):
        return self.__digest

    def hexdigest(self):
        return "{:08x}".format(self.__digest)

    def update(self, arg):
        self.__digest = zlib.crc32(arg, self.__digest) & 0xFFFFFFFF

15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
"""Returns a table of file names with the following informations

"""

__author__ = "Patrick Vergain <pvergain@gmail.com>"


import hashlib
import logging
import zlib

from unipath import Path


log = logging.getLogger("get_table_hash")


class crc32(object):
    """hashlib-compatible interface for CRC-32 support

    http://stackoverflow.com/questions/1742866/compute-crc-of-file-in-python
    """

    name = "crc32"
    digest_size = 4
    block_size = 1

    def __init__(self, arg=""):
        self.__digest = 0
        self.update(arg)

    def copy(self):
        copy = super(self.__class__, self).__new__(__class__)
        copy.__digest = self.__digest
        return copy

    def digest(self):
        return self.__digest

    def hexdigest(self):
        return "{:08x}".format(self.__digest)

    def update(self, arg):
        self.__digest = zlib.crc32(arg, self.__digest) & 0xFFFFFFFF

.. literalinclude:: example.py
   :diff: example.py.orig

--- /home/docs/checkouts/readthedocs.org/user_builds/devopstutodoc/checkouts/latest/doc_generators/sphinx/rest_sphinx/code/literalinclude/example.py.orig
+++ /home/docs/checkouts/readthedocs.org/user_builds/devopstutodoc/checkouts/latest/doc_generators/sphinx/rest_sphinx/code/literalinclude/example.py
@@ -1,38 +1,31 @@
-# -*- coding: UTF-8 -*-
-'''Returns a table of file names with the following informations
+"""Returns a table of file names with the following informations
 
-'''
+"""
 
-__author__ = 'Patrick Vergain <pvergain@gmail.com>'
+__author__ = "Patrick Vergain <pvergain@gmail.com>"
 
 
 import hashlib
-
-# see http://petl.readthedocs.org/en/latest/
-# Extract, Transform and Load (Tables of Data)
-from petl import look
-import glob
-import os
-import argparse
 import logging
 import zlib
-import sys
 
 from unipath import Path
 
 
-log = logging.getLogger('get_table_hash')
+log = logging.getLogger("get_table_hash")
+
 
 class crc32(object):
-    '''hashlib-compatible interface for CRC-32 support
+    """hashlib-compatible interface for CRC-32 support
 
     http://stackoverflow.com/questions/1742866/compute-crc-of-file-in-python
-    '''
-    name = 'crc32'
+    """
+
+    name = "crc32"
     digest_size = 4
     block_size = 1
 
-    def __init__(self, arg=''):
+    def __init__(self, arg=""):
         self.__digest = 0
         self.update(arg)
 
@@ -45,7 +38,7 @@
         return self.__digest
 
     def hexdigest(self):
-        return '{:08x}'.format(self.__digest)
+        return "{:08x}".format(self.__digest)
 
     def update(self, arg):
-        self.__digest = zlib.crc32(arg, self.__digest) & 0xffffffff
+        self.__digest = zlib.crc32(arg, self.__digest) & 0xFFFFFFFF

.. literalinclude:: example.py
   :linenos:
   :caption:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
"""Returns a table of file names with the following informations

"""

__author__ = "Patrick Vergain <pvergain@gmail.com>"


import hashlib
import logging
import zlib

from unipath import Path


log = logging.getLogger("get_table_hash")


class crc32(object):
    """hashlib-compatible interface for CRC-32 support

    http://stackoverflow.com/questions/1742866/compute-crc-of-file-in-python
    """

    name = "crc32"
    digest_size = 4
    block_size = 1

    def __init__(self, arg=""):
        self.__digest = 0
        self.update(arg)

    def copy(self):
        copy = super(self.__class__, self).__new__(__class__)
        copy.__digest = self.__digest
        return copy

    def digest(self):
        return self.__digest

    def hexdigest(self):
        return "{:08x}".format(self.__digest)

    def update(self, arg):
        self.__digest = zlib.crc32(arg, self.__digest) & 0xFFFFFFFF

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

   def some_function():
       interesting = False
       print 'This line is highlighted.'
       print 'This one is not...'
       print '...but this one is.'

def some_function():
    interesting = False
    print 'This line is highlighted.'
    print 'This one is not...'
    print '...but this one is.'

.. literalinclude:: example.py
   :lines: 1,3,5-10,20-

.. literalinclude:: example.py
   :language: python
   :encoding: latin-1

.. literalinclude:: example.py
   :pyobject: Timer.start

.. c:function:: DWORD CR_RFID_VerifierPIN(ST_CODE_PIN *pCodePIN)

    Le code PIN permet d'autoriser l'utilisation des clés de chiffrement et de
    signature dans le lecteur RFID.

    :Paramètres:
        :entree:
            :pCodePIN: le code PIN à présenter au lecteur RFID.

    :Returns:
       :error:  :ref:`see the error codes <list_error_codes>`
       :success:  :ref:`COMMAND_SUCCESS <cr_success>`

de  Luc Saffre <luc.saffre@gmail.com>
heure de l'expéditeur   Envoyé à 14:26 (GMT+02:00). Heure locale : 17:00. ✆
répondre à  sphinx-dev@googlegroups.com
à   sphinx-dev <sphinx-dev@googlegroups.com>
date    18 février 2011 14:26
objet   [sphinx-dev] toctree glob ordering
liste de diffusion  <sphinx-dev.googlegroups.com> Filtrer les messages de cette liste de diffusion

.. toctree::
  :maxdepth: 1
  :glob:

  ?
  ??

.. image:: picture.png

.. image:: picture.jpeg
   :height: 100px
   :width: 200 px
   :scale: 50 %
   :alt: alternate text
   :align: right

.. image:: ../images/wiki_logo_openalea.png

.. image:: ../images/wiki_logo_openalea.png
    :width: 200px
    :align: center
    :height: 100px
    :alt: alternate text

.. figure:: ../images/wiki_logo_openalea.png
    :width: 200px
    :align: center
    :height: 100px
    :alt: alternate text
    :figclass: align-center

    figure are like images but with a caption

    and whatever else you wish to add

    .. code-block:: python

        import image

import image

.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
=============== ======================================================
 |MatBasicIma|  **Title:** :ref:`matTheBasicImageContainer`
                *Compatibility:* > OpenCV 2.0
                *Author:* |Author_BernatG|
                You will learn how to store images in the memory and how to print out their content to the console.
=============== ======================================================
.. |MatBasicIma| image:: images/matTheBasicImageStructure.jpg
                 :height: 90pt
                 :width:  90pt

.. figure:: pagelogo_geoserver.png
   :align: center

   *The GeoServer logo as shown on the homepage.*

.. |biohazard| image:: biohazard.png

The |biohazard| symbol must be used on containers used to dispose of medical waste.

.. |doctest| replace:: :mod:`doctest`

I really like |doctest|.

* This is a bulleted list.
* It has two items, the second
  item uses two lines.

1. This is a numbered list.
2. It has two items too.

#. This is a numbered list.
#. It has two items too.

A. First item
B. Second item

* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list continues

term (up to a line of text)
   Definition of the term, which must be indented

   and can even consist of multiple paragraphs

next term
   Description.

This is a normal text paragraph. The next paragraph is a code sample::

   It is not processed in any way, except
   that the indentation is removed.

   It can span multiple lines.

This is a normal text paragraph again.

.. include myfile.rst

.. code-block:: python

With two colons you start a code block using the default highlighter::

        # Some Python code here
        # The language defaults to Python, we don't need to set it
        if 1 == 2:
                pass

# Some Python code here
# The language defaults to Python, we don't need to set it
if 1 == 2:
    pass

.. code-block:: python

        if "foo" == "bar":
                # This is Python code
                pass

if "foo" == "bar":
    # This is Python code
    pass

.. code-block:: xml

        <somesnippet>Some XML</somesnippet>

<somesnippet>Some XML</somesnippet>

.. code-block:: console

   # A comment
   sh myscript.sh

# A comment
sh myscript.sh

.. code-block:: ini

   [some-part]
   # A random part in the buildout
   recipe = collective.recipe.foo
   option = value

[some-part]
# A random part in the buildout
recipe = collective.recipe.foo
option = value

.. code-block:: pycon

   >>> class Foo:
   ...     bar = 100
   ...
   >>> f = Foo()
   >>> f.bar
   100
   >>> f.bar / 0
   Traceback (most recent call last):
         File "<stdin>", line 1, in <module>
   ZeroDivisionError: integer division or modulo by zero

>>> class Foo:
...     bar = 100
...
>>> f = Foo()
>>> f.bar
100
>>> f.bar / 0
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ZeroDivisionError: integer division or modulo by zero

.. highlight:: console

some shell commands

.. csv-table:: Balance Sheet
   :header: Description,In,Out,Balance
   :widths: 20, 10, 10, 10
   :stub-columns: 1

   Travel,,230.00,-230.00
   Fees,,400.00,-630.00
   Grant,700.00,,70.00
   Train Fare,,70.00,**0.00**

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...      |          |
+------------------------+------------+----------+----------+

+---------------------------------+------------+
| Condition                       | Decision   |
+=================================+============+
| comparison score >= threshold   | Match      |
+---------------------------------+------------+
| comparison score < threshold    | Non-Match  |
+---------------------------------+------------+

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Shapes
     - Description
   * - Square
     - Four sides of equal length, 90 degree angles
   * - Rectangle
     - Four sides, 90 degree angles

.. list-table::
   :widths: 33 33 33
   :header-rows: 1

   * -
     -
     -

   * - .. image:: image_selection/up_image1.png
     - .. image:: image_selection/up_image2.png
     - .. image:: image_selection/up_image3.png

   * - .. image:: image_selection/down_image4.png
     - .. image:: image_selection/down_image5.png
     - .. image:: image_selection/down_image6.png

.. list-table::
   :widths: 20 60 20
   :header-rows: 1

   * - Error type
     - Definition
     - Impact

   * - False Match
     - Comparison decision of “match” for a biometric probe and a biometric
       reference that are from different fingers
     - System security lack

   * - False Non-Match
     - Comparison decision of “non-match” for a biometric probe and a biometric
       reference that are from the same finger
     - User inconvenience

.. flat-table:: table title
   :header-rows: 2
   :stub-columns: 1
   :widths: 1 1 1 1 2

   * - :rspan:`1` head / stub
     - :cspan:`3` head 1.1-4

   * - head 2.1
     - head 2.2
     - head 2.3
     - head 2.4

   * .. row body 1 / this is a comment

     - row 1
     - :rspan:`2` cell 1-3.1
     - cell 1.2
     - cell 1.3
     - cell 1.4

   * .. Comments and targets are allowed on *table-row* stage.
     .. _`row body 2`:

     - row 2
     - cell 2.2
     - :rspan:`1` :cspan:`1`
       cell 2.3 with a span over

       * col 3-4 &
       * row 2-3

   * - row 3
     - cell 3.2

   * - row 4
     - cell 4.1
     - cell 4.2
     - cell 4.3
     - cell 4.4

   * - row 5
     - cell 5.1 with automatic span to rigth end

   * - row 6
     - cell 6.1
     - ..

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

Example of external link:  `reST role <http://sphinx-doc.org/latest/markup/inline.html#role-ref>`_ .

:ref:`link to internal links <internal_links>`

=================
This is a heading
=================

.. function:: foo(x)
              foo(y, z)
   :bar: no

   Return a line of text input from the user.

Lorem ipsum [#]_ dolor sit amet ... [#]_

.. rubric:: Footnotes

.. [#] Text of the first footnote.
.. [#] Text of the second footnote.

.. function:: foo(x)
              foo(y, z)
   :bar: no

   Return a line of text input from the user.

Lorem ipsum [#]_ dolor sit amet ... [#]_

.. rubric:: Footnotes

.. [#] Text of the first footnote.
.. [#] Text of the second footnote.

.. sidebar:: Sidebar Title
        :subtitle: Optional Sidebar Subtitle

   Subsequent indented lines comprise
   the body of the sidebar, and are
   interpreted as body elements.

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autodoc.typehints']

$ sphinx-autogen -o generated *.rst

sphinx.util.relative_uri
========================

.. autofunction:: sphinx.util.relative_uri

.. confval:: autosummary_generate

Remark:
   We use a :ref:`Python3.6 docker image <docker:tuto_docker>`.

1
2
3
4
5
6
7
8
9
     extensions = [
             'sphinx.ext.intersphinx',
             'sphinx.ext.todo',
     ]

     intersphinx_mapping = {
             'python': ('https://docs.python.org/', None),
             'docker': ('https://gdevops.gitlab.io/tuto_docker/', None),
     }

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
#
# Configuration file for the Sphinx documentation builder.
# http://www.sphinx-doc.org/en/stable/config

from datetime import datetime

project = "Tuto Documentation"
author = "DevOps people"
version = "0.1.0"
release = version
now = datetime.now()
today = f"{now.year}-{now.month:02}-{now.day:02} {now.hour:02}H{now.minute:02}"
copyright = f"2009-{now.year}, {author}"
source_suffix = {
    ".rst": "restructuredtext",
    ".md": "markdown",
}
master_doc = "index"
language = None
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".venv"]
html_theme = "bizstyle"
pygments_style = "sphinx"
extensions = ["sphinx.ext.intersphinx", "recommonmark", "sphinx_tabs.tabs"]
intersphinx_mapping = {
    "python": ("https://docs.python.org/", None),
    "official_sphinx": ("http://www.sphinx-doc.org/", None),
    "https://gdevops.gitlab.io/tuto_python/": None,
    "https://gdevops.gitlab.io/tuto_django/": None,
    "docker": ("https://gdevops.gitlab.io/tuto_docker/", None),
    "https://gdevops.gitlab.io/tuto_cli/": None,
    "https://gdevops.gitlab.io/tuto_build/": None,
    "https://gdevops.gitlab.io/tuto_kubernetes/": None,
    "http://blockdiag.com/en/": None,
}
extensions = extensions + ["sphinx.ext.todo"]
todo_include_todos = True




###########################################################################
#          auto-created readthedocs.org specific configuration            #
###########################################################################


#
# The following code was added during an automated build on readthedocs.org
# It is auto created and injected for every build. The result is based on the
# conf.py.tmpl file found in the readthedocs.org codebase:
# https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl
#


import importlib
import sys
import os.path
from six import string_types

from sphinx import version_info

# Get suffix for proper linking to GitHub
# This is deprecated in Sphinx 1.3+,
# as each page can have its own suffix
if globals().get('source_suffix', False):
    if isinstance(source_suffix, string_types):
        SUFFIX = source_suffix
    elif isinstance(source_suffix, (list, tuple)):
        # Sphinx >= 1.3 supports list/tuple to define multiple suffixes
        SUFFIX = source_suffix[0]
    elif isinstance(source_suffix, dict):
        # Sphinx >= 1.8 supports a mapping dictionary for multiple suffixes
        SUFFIX = list(source_suffix.keys())[0]  # make a ``list()`` for py2/py3 compatibility
    else:
        # default to .rst
        SUFFIX = '.rst'
else:
    SUFFIX = '.rst'

# Add RTD Static Path. Add to the end because it overwrites previous files.
if not 'html_static_path' in globals():
    html_static_path = []
if os.path.exists('_static'):
    html_static_path.append('_static')

# Add RTD Theme only if they aren't overriding it already
using_rtd_theme = (
    (
        'html_theme' in globals() and
        html_theme in ['default'] and
        # Allow people to bail with a hack of having an html_style
        'html_style' not in globals()
    ) or 'html_theme' not in globals()
)
if using_rtd_theme:
    theme = importlib.import_module('sphinx_rtd_theme')
    html_theme = 'sphinx_rtd_theme'
    html_style = None
    html_theme_options = {}
    if 'html_theme_path' in globals():
        html_theme_path.append(theme.get_html_theme_path())
    else:
        html_theme_path = [theme.get_html_theme_path()]

if globals().get('websupport2_base_url', False):
    websupport2_base_url = 'https://readthedocs.org/websupport'
    websupport2_static_url = 'https://assets.readthedocs.org/static/'


#Add project information to the template context.
context = {
    'using_theme': using_rtd_theme,
    'html_theme': html_theme,
    'current_version': "latest",
    'version_slug': "latest",
    'MEDIA_URL': "https://media.readthedocs.org/",
    'STATIC_URL': "https://assets.readthedocs.org/static/",
    'PRODUCTION_DOMAIN': "readthedocs.org",
    'versions': [
    ("latest", "/en/latest/"),
    ("stable", "/en/stable/"),
    ("0.3.0", "/en/0.3.0/"),
    ("0.1.0", "/en/0.1.0/"),
    ],
    'downloads': [ 
    ("pdf", "//devopstutodoc.readthedocs.io/_/downloads/en/latest/pdf/"),
    ("html", "//devopstutodoc.readthedocs.io/_/downloads/en/latest/htmlzip/"),
    ],
    'subprojects': [ 
    ],
    'slug': 'devopstutodoc',
    'name': u'devopstuto_doc',
    'rtd_language': u'en',
    'programming_language': u'py',
    'canonical_url': 'https://devopstutodoc.readthedocs.io/en/latest/',
    'analytics_code': '',
    'single_version': False,
    'conf_py_path': '/',
    'api_host': 'https://readthedocs.org',
    'github_user': 'None',
    'github_repo': 'None',
    'github_version': 'master',
    'display_github': False,
    'bitbucket_user': 'None',
    'bitbucket_repo': 'None',
    'bitbucket_version': 'master',
    'display_bitbucket': False,
    'gitlab_user': 'gdevops',
    'gitlab_repo': 'tuto_documentation',
    'gitlab_version': 'master',
    'display_gitlab': True,
    'READTHEDOCS': True,
    'using_theme': (html_theme == "default"),
    'new_theme': (html_theme == "sphinx_rtd_theme"),
    'source_suffix': SUFFIX,
    'ad_free': False,
    'user_analytics_code': '',
    'global_analytics_code': 'UA-17997319-1',
    'commit': '79bea070',
}




if 'html_context' in globals():
    
    html_context.update(context)
    
else:
    html_context = context

# Add custom RTD extension
if 'extensions' in globals():
    # Insert at the beginning because it can interfere
    # with other extensions.
    # See https://github.com/rtfd/readthedocs.org/pull/4054
    extensions.insert(0, "readthedocs_ext.readthedocs")
else:
    extensions = ["readthedocs_ext.readthedocs"]

# Add External version warning banner to the external version documentation
if 'branch' == 'external':
    extensions.insert(1, "readthedocs_ext.external_version_warning")

project_language = 'en'

# User's Sphinx configurations
language_user = globals().get('language', None)
latex_engine_user = globals().get('latex_engine', None)
latex_elements_user = globals().get('latex_elements', None)

# Remove this once xindy gets installed in Docker image and XINDYOPS
# env variable is supported
# https://github.com/rtfd/readthedocs-docker-images/pull/98
latex_use_xindy = False

chinese = any([
    language_user in ('zh_CN', 'zh_TW'),
    project_language in ('zh_CN', 'zh_TW'),
])

japanese = any([
    language_user == 'ja',
    project_language == 'ja',
])

if chinese:
    latex_engine = latex_engine_user or 'xelatex'

    latex_elements_rtd = {
        'preamble': '\\usepackage[UTF8]{ctex}\n',
    }
    latex_elements = latex_elements_user or latex_elements_rtd
elif japanese:
    latex_engine = latex_engine_user or 'platex'

Takayuki Shimizukawa shimizukawa@gmail.com
répondre à:  sphinx-dev@googlegroups.com
à:   sphinx-dev@googlegroups.com
date:    30 octobre 2012 05:22
objet:   Re: [sphinx-dev] Include HTML in generated Sphinx docs

Takayuki SHIMIZUKAWA
Sphinx-users.jp

extensions = ['sphinx.ext.intersphinx']

intersphinx_mapping = {
    'javaapi': ('http://api.example.com/', 'javaapi.inv'),
}

inventory_header = u'''\
# Sphinx inventory version 2
# Project: javaapi
# Version: 2.0
# The remainder of this file is compressed with zlib.
'''.encode('utf-8')

inventory_payload = u'''\
api1 std:label -1 api.html#api1 API 1
'''.encode('utf-8')

# inventory_payload lines spec:
#   name domainname:type priority uri dispname
#
# * `name`     -- fully qualified name
# * `dispname` -- name to display when searching/linking
# * `type`     -- object type, a key in ``self.object_types``
# * `docname`  -- the document where it is to be found
# * `anchor`   -- the anchor name for the object
# * `priority` -- how "important" the object is (determines placement in search results)
#
#   - 1: default priority (placed before full-text matches)
#   - 0: object is important (placed before default-priority objects)
#   - 2: object is unimportant (placed after full-text matches)
#   - -1: object should not show up in search at all
#

inventory = inventory_header + zlib.compress(inventory_payload)
open('javaapi.inv','wb').write(inventory)

<div class="section" id="example-link-to-outer-non-sphinx-by-using-intersphinx">
<h1>Example: Link to outer non-sphinx by using intersphinx<a class="headerlink" href="#example-link-to-outer-non-sphinx-by-using-intersphinx" title="Permalink to this headline">ﾂｶ</a></h1>
<p><a class="reference external" href="http://api.example.com/api.html#api1" title="(in javaapi v2.0)"><em class="xref std std-ref">Java API 1</em></a></p>
</div>

Example: Link to outer non-sphinx by using intersphinx
==========================================================================

:ref:`Java API 1 <javaapi:api1>`

:param path: The path of the file to wrap
:type path: str
:param field_storage: The :class:`FileStorage` instance to wrap
:type field_storage: FileStorage
:param temporary: Whether or not to delete the file when the File
   instance is destructed
:type temporary: bool
:returns: A buffered writable file descriptor
:rtype: BufferedFileStorage

Args:
    path (str): The path of the file to wrap
    field_storage (FileStorage): The :class:`FileStorage` instance to wrap
    temporary (bool): Whether or not to delete the file when the File
       instance is destructed

Returns:
    BufferedFileStorage: A buffered writable file descriptor

# conf.py

# Add autodoc and napoleon to the extensions list
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']

$ sphinx-apidoc -f -o docs/source projectdir

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    """
    return True

.. runblock:: pycon

    >>> for i in range(5):
    ...    print i

>>> for i in range(5):
...    print i
1
2
3
4
5

.. runblock:: console

    $ date

$ date
Thu  4 Mar 2010 22:56:49 EST

$ hg clone http://bitbucket.org/birkenfeld/sphinx-contrib/
$ cd sphinx-contrib/autorun
$ python setup.py install

extensions.append('sphinxcontrib.autorun')

.. blockdiag::

   {
      planners -> seq-mco -> seq-mco-planner-11;
      planners -> seq-mco -> seq-mco-planner-12;
      planners -> seq-mco -> "seq-mco-planner-1...";
      planners -> seq-opt -> seq-opt-planner-21;
      planners -> seq-opt -> seq-opt-planner-22;
      planners -> seq-opt -> "seq-mco-planner-2...";
      planners -> seq-sat -> seq-sat-planner-31;
      planners -> seq-sat -> seq-sat-planner-32;
      planners -> seq-sat -> "seq-mco-planner-3...";
      planners -> tempo-sat -> tempo-sat-planner-41;
      planners -> tempo-sat -> tempo-sat-planner-42;
      planners -> tempo-sat -> "seq-mco-planner-4...";
   }

cd /tmp/doxygen-1.7.2
./configure --prefix /opt/doxygen/1.7.2 --with-doxywizard
make

su - root
cd /opt/doxygen
ln -s 1.7.2 current

pip install sphinxcontrib-doxylink

hg clone http://bitbucket.org/birkenfeld/sphinx-contrib
cd sphinx-contrib/doxylink
python setup.py install

:doxy:`choleskyDecomposition`



python copytree_doxygen.py

pause

"""
Copie des données doxygen.

Les données générées par doxygen sont dans le répertoire doxygen/html

Il faut copier ces données dans le répertoire sphinx/_build/html/_downloads

Précondition: le répertoire destination doit être vide.

.. function:: copytree(src, dst[, symlinks=False[, ignore=None]])

   Recursively copy an entire directory tree rooted at *src*.  The destination
   directory, named by *dst*, must not already exist; it will be created as well
   as missing parent directories.  Permissions and times of directories are
   copied with :func:`copystat`, individual files are copied using
   :func:`copy2`.


.. function:: rmtree(path[, ignore_errors[, onerror]])

   .. index:: single: directory; deleting

   Delete an entire directory tree; *path* must point to a directory (but not a
   symbolic link to a directory).  If *ignore_errors* is true, errors resulting
   from failed removals will be ignored; if false or omitted, such errors are
   handled by calling a handler specified by *onerror* or, if that is omitted,
   they raise an exception.

"""

from shutil import copytree, rmtree


destination = "_build/html/_downloads"

# le répertoire destination doit être vide
rmtree(destination)

# copie vers le répertoire destination
copytree(src="../doxygen/html", dst=destination)

Le but de la bibliothèque logicielle est de proposer une API C permettant la
communication entre:

- l'application :term:`EUCLIDE`
- un ensemble de 40 :term:`boîtiers`
- un :term:`lecteur de cartes à puces` (RFID)
- une :term:`clé RF`


:download:`Télécharger  la documentation doxygen du projet CR_Euclide <../doxygen/html/index.html>`.

.. _doxygen_documentation:

=======================
Doxygen Documentation
=======================

:download:`Télécharger  la documentation doxygen du projet CR_Euclide <../../../doxygen/html/index.html>`.

+---doxygen
|   |   TagFile.xml
|   |
|   +---def
|   |       doxygen.def
|   |
|   \---html
|       |   annotated.html
|       |   bc_s.png
|       |   classes.html
|       |   class_ryb_eliot_1_1_antennas-members.html
|       |   _write_tag_form_8cs_source.html
|       |   _write_tag_form_8_designer_8cs.html
|       |   _write_tag_form_8_designer_8cs_source.html
|       |
|
\---sphinx
    |   index.rst
    |   make.bat
    |   Makefile
    |
    |
    +---_build
    |   \---html
    |       +---_downloads
    |       |   |   annotated.html
    |       |   |   bc_s.png
    |       |   |   classes.html
    |       |   |
    |       |   \---search
    |       |           all_5f.html
    |       |           all_61.html
    |
    +---_static
    \---_templates

python doxy.py –i  doxy_xml_dir –o rst_dir –t func

python doxy.py –i  doxy_xml_dir –o rst_dir –t typedef

python doxy.py –i  doxy_xml_dir –o rst_dir

python doxy.py –i  doxy_xml_dir –o rst_dir -t all

.. toctree::
    :maxdepth: 1

    refs/index.rst

sphinx-build source_dir build_dir

GENERATE_TAGFILE       = krb5doxy.tag
GENERATE_XML           = YES

extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.doxylink']
doxylink = { ' krb5doxy' : ('/tmp/krb5doxy.tag, ' doxy_html_dir ') }

extensions = [
    'hieroglyph',
]

$ sphinx-build -b slides sourcedir outdir

pipenv install -e git+http://github.com/return42/linuxdoc.git#egg=master

git clone https://github.com/return42/linuxdoc
cd linuxdoc
make install

# https://return42.github.io/linuxdoc/install.html
extensions = extensions + [
    "linuxdoc.rstFlatTable",  # Implementation of the 'flat-table' reST-directive.
    "linuxdoc.rstKernelDoc",  # Implementation of the 'kernel-doc' reST-directive.
    "linuxdoc.kernel_include",  # Implementation of the 'kernel-include' reST-directive.
    "linuxdoc.manKernelDoc",  # Implementation of the 'kernel-doc-man' builder
    "linuxdoc.cdomain",  # Replacement for the sphinx c-domain.
    "linuxdoc.kfigure",  # Sphinx extension which implements scalable image handling.
]

pip install sphinx-tabs

extensions = ['sphinx_tabs.tabs']

https://github.com/djungelorm/sphinx-tabs/releases/download/v1.1.12/sphinx-tabs-1.1.13.tar.gz

.. tabs::

   .. tab:: Apples

      Apples are green, or sometimes red.

   .. tab:: Pears

      Pears are green.

   .. tab:: Oranges

      Oranges are orange.

.. tabs::

   .. group-tab:: Linux

      Linux Line 1

   .. group-tab:: Mac OSX

      Mac OSX Line 1

   .. group-tab:: Windows

      Windows Line 1

.. tabs::

   .. group-tab:: Linux

      Linux Line 2

   .. group-tab:: Mac OSX

      Mac OSX Line 2

   .. group-tab:: Windows

      Windows Line 2

.. tabs::

   .. code-tab:: c

         int main(const int argc, const char **argv) {
           return 0;
         }

   .. code-tab:: c++

         int main(const int argc, const char **argv) {
           return 0;
         }

   .. code-tab:: py

         def main():
             return

   .. code-tab:: java

         class Main {
             public static void main(String[] args) {
             }
         }

   .. code-tab:: julia

         function main()
         end

   .. code-tab:: fortran

         PROGRAM main
         END PROGRAM main

int main(const int argc, const char **argv) {
  return 0;
}

int main(const int argc, const char **argv) {
  return 0;
}

def main():
    return

class Main {
    public static void main(String[] args) {
    }
}

function main()
end

PROGRAM main
END PROGRAM main

npm install -g jsdoc

pip install sphinx-js

cd my-project
sphinx-quickstart

  > Root path for the documentation [.]: docs
  > Separate source and build directories (y/n) [n]:
  > Name prefix for templates and static dir [_]:
  > Project name: My Project
  > Author name(s): Fred Fredson
  > Project version []: 1.0
  > Project release [1.0]:
  > Project language [en]:
  > Source file suffix [.rst]:
  > Name of your master document (without suffix) [index]:
  > Do you want to use the epub builder (y/n) [n]:
  > autodoc: automatically insert docstrings from modules (y/n) [n]:
  > doctest: automatically test code snippets in doctest blocks (y/n) [n]:
  > intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
  > todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:
  > coverage: checks for documentation coverage (y/n) [n]:
  > imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
  > mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
  > ifconfig: conditional inclusion of content based on config values (y/n) [n]:
  > viewcode: include links to the source code of documented Python objects (y/n) [n]:
  > githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:
  > Create Makefile? (y/n) [y]:
  > Create Windows command file? (y/n) [y]:

extensions = ['sphinx_js']

primary_domain = 'js'

plantuml = ['java', '-jar', '/path/to/plantuml.jar']

% cat <<EOT > /usr/local/bin/plantuml
#!/bin/sh -e
java -jar /path/to/plantuml.jar "$@"
EOT

% chmod +x /usr/local/bin/plantuml

.. uml::

   Alice -> Bob: Hi!
   Alice <- Bob: How are you?

pip install -e git+https://github.com/alendit/sphinx-pyreverse.git

.. uml::
        {{path to the module}}

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path .
exclude_patterns = [
        '_build',
        'Thumbs.db',
        '.DS_Store',
        # pipenv virtualenv with PIPENV_VENV_IN_PROJECT=1
        '.venv'
]

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
 # -*- coding: utf-8 -*-
 #
 # Configuration file for the Sphinx documentation builder.
 #
 # This file does only contain a selection of the most common options. For a
 # full list see the documentation:
 # http://www.sphinx-doc.org/en/stable/config

 # -- Path setup --------------------------------------------------------------

 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
 import re
 import sys
 sys.path.insert(0, os.path.abspath('.'))
 sys.path.insert(0, os.path.abspath('..'))

 from unittest.mock import MagicMock

 class Mock(MagicMock):
     @classmethod
     def __getattr__(cls, name):
         return MagicMock()

 MOCK_MODULES = ['aiosqlite', 'astroid', 'asyncpg', 'asynctest', 'aiomysql']
 sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)


 # -- Project information -----------------------------------------------------


 project = 'Tortoise'
 copyright = '2018, Andrey Bondar'
 author = 'Andrey Bondar'


 def get_version():
     verstrline = open('../tortoise/__init__.py', "rt").read()
     mob = re.search(r"^__version__ = ['\"]([^'\"]*)['\"]", verstrline, re.M)
     if mob:
         return mob.group(1)
     else:
         raise RuntimeError("Unable to find version string")


 # The short X.Y version
 version = get_version()
 # The full version, including alpha/beta/rc tags
 release = version


 # -- General configuration ---------------------------------------------------

 # If your documentation needs a minimal Sphinx version, state it here.
 #
 # needs_sphinx = '1.0'

 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
     'sphinx_autodoc_typehints',
     'sphinx.ext.todo',

     # cloud's extensions
     'cloud_sptheme.ext.autodoc_sections',
     'cloud_sptheme.ext.relbar_links',
     'cloud_sptheme.ext.escaped_samp_literals',
     'cloud_sptheme.ext.table_styling',
 ]

 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
 source_suffix = '.rst'

 # The master toctree document.
 master_doc = 'toc'

 # The frontpage document.
 index_doc = 'index'

 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
 language = None

 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path .
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'

 # Todo settings
 todo_include_todos = True
 todo_emit_warnings = True

 # Napoleon settings
 napoleon_google_docstring = False
 napoleon_numpy_docstring = True
 napoleon_include_init_with_doc = False
 napoleon_include_private_with_doc = False
 napoleon_include_special_with_doc = True
 napoleon_use_admonition_for_examples = True
 napoleon_use_admonition_for_notes = True
 napoleon_use_admonition_for_references = True
 napoleon_use_ivar = True
 napoleon_use_param = True
 napoleon_use_rtype = True

 # -- Options for HTML output -------------------------------------------------
 import cloud_sptheme as csp

 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
 html_theme = 'greencloud'

 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
 html_theme_options = {
     'borderless_decor': True,
     'roottarget': index_doc,
     'sidebarwidth': '3in',
     'hyphenation_language': 'en',
 }

 # Add any paths that contain custom themes here, relative to this directory.
 html_theme_path = [csp.get_theme_dir()]

 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 html_title = "%s v%s Documentation" % (project, release)

 # A shorter title for the navigation bar.  Default is the same as html_title.
 html_short_title = "%s %s Documentation" % (project, version)

 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 #
 html_logo = os.path.join("_static", "tortoise.png")

 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']

 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
 #
 # The default sidebars (for documents that don't match any pattern) are
 # defined by theme itself.  Builtin themes are using these templates by
 # default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
 # 'searchbox.html']``.
 #
 html_sidebars = {
     '**': [
         'searchbox.html',
         'space.html',
         'globaltoc.html',
     ]
 }


 # -- Options for HTMLHelp output ---------------------------------------------

 # Output file base name for HTML help builder.
 htmlhelp_basename = 'tortoisedoc'


 # -- Options for LaTeX output ------------------------------------------------

 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',

     # The font size ('10pt', '11pt' or '12pt').
     #
     # 'pointsize': '10pt',

     # Additional stuff for the LaTeX preamble.
     #
     # 'preamble': '',

     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
 }

 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
     (master_doc, 'tortoise.tex', 'tortoise Documentation',
      'Andrey Bondar', 'manual'),
 ]


 # -- Options for manual page output ------------------------------------------

 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
     (master_doc, 'tortoise', 'tortoise Documentation',
      [author], 1)
 ]


 # -- Options for Texinfo output ----------------------------------------------

 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
     (master_doc, 'tortoise', 'tortoise Documentation',
      author, 'tortoise', 'One line description of project.',
      'Miscellaneous'),
 ]


 # -- Extension configuration -------------------------------------------------

Georg Brandl georg.brandl@gmail.com
répondre à:  sphinx-users@googlegroups.com
à:   sphinx-users@googlegroups.com
date:        5 mars 2014 07:50
objet:       Re: [sphinx-users] Another project using Sphinx: Ceph

<gsavix@gmail.com>
heure de l'expéditeur   Envoyé à 13:15 (GMT-02:00). Heure locale : 10:35. ✆
répondre à  sphinx-dev@googlegroups.com
à   sphinx-dev@googlegroups.com
date    18 février 2011 13:15
objet   Re: [sphinx-dev] GSoC and Breathe
liste de diffusion  <sphinx-dev.googlegroups.com> Filtrer les messages de cette liste de diffusion

    class Github(object):

        def __init__(self, username=None, api_token=None, requests_per_second=None,
                     access_token=None, cache=None, proxy_host=None,
                     proxy_port=8080):
            """
            An interface to GitHub's API:
            http://develop.github.com/

            .. versionadded:: 0.2.0
            The ``requests_per_second`` parameter
            .. versionadded:: 0.3.0
            The ``cache`` and ``access_token`` parameters
            .. versionadded:: 0.4.0
            The ``proxy_host`` and ``proxy_port`` parameters

            :param str username: your own GitHub username.
            :param str api_token: can be found at https://github.com/account
            (while logged in as that user):
            :param str access_token: can be used when no ``username`` and/or
            ``api_token`` is used. The ``access_token`` is the OAuth access
            token that is received after successful OAuth authentication.
            :param float requests_per_second: indicate the API rate limit you're
            operating under (1 per second per GitHub at the moment),
            or None to disable delays. The default is to disable delays (for
            backwards compatibility).
            :param str cache: a directory for caching GitHub responses.
            :param str proxy_host: the hostname for the HTTP proxy, if needed.
            :param str proxy_port: the hostname for the HTTP proxy, if needed (will
            default to 8080 if a proxy_host is set and no port is set).
            """

        self.request = GithubRequest(username=username, api_token=api_token,
                                     requests_per_second=requests_per_second,
                                     access_token=access_token, cache=cache,
                                     proxy_host=proxy_host,
                                     proxy_port=proxy_port)
        self.issues = Issues(self.request)
        self.users = Users(self.request)
        self.repos = Repositories(self.request)
        self.commits = Commits(self.request)
        self.organizations = Organizations(self.request)
        self.teams = Teams(self.request)
        self.pull_requests = PullRequests(self.request)


def get_network_meta(self, project):
    """Get Github metadata associated with a project

    :param str project: GitHub project
    """
     return self.request.raw_request("/".join([self.request.github_url,
                                              project,
                                              "network_meta"]), {})

def get_network_data(self, project, nethash, start=None, end=None):
    """Get chunk of Github network data

    :param str project: GitHub project
    :param str nethash: identifier provided by ``get_network_meta``
    :param int start: optional start point for data
    :param int stop: optional end point for data
    """
    data = {"nethash": nethash}
    if start:
        data["start"] = start
    if end:
        data["end"] = end

    return self.request.raw_request("/".join([self.request.github_url,
                                              project,
                                              "network_data_chunk"]),
                                              data)

def _handle_naive_datetimes(f):
    """Decorator to make datetime arguments use GitHub timezone

    :param func f: Function to wrap
    """
    def wrapper(datetime_):
        if not datetime_.tzinfo:
            datetime_ = datetime_.replace(tzinfo=GITHUB_TZ)
        else:
            datetime_ = datetime_.astimezone(GITHUB_TZ)
        return f(datetime_)
    wrapped = wrapper
    wrapped.__name__ = f.__name__
    wrapped.__doc__ = (
        f.__doc__
        + """\n    .. note:: Supports naive and timezone-aware datetimes"""
    )
    return wrapped


@_handle_naive_datetimes
def datetime_to_ghdate(datetime_):
    """Convert Python datetime to Github date string

    :param datetime datetime_: datetime object to convert
    """
    return datetime_.strftime(GITHUB_DATE_FORMAT)

>>> import macaron
>>> macaron.macaronage(dbfile="members.db")
>>> team = Team.create(name="Houkago Tea Time")
>>> team.members.append(name="Azusa", part="Gt2")
<Member object 1>
>>> macaron.bake()
>>> azu = Member.get("part=?", ["Gt2"])
>>> print azu
<Member 'Azusa : Gt2'>
>>> macaron.db_close()

Am 11.02.2014 09:36, schrieb manon.midy@enalean.com:
> Hi,
>
> I'm working at Enalean, the software provider of Tuleap Open ALM, the first 100%
> Open Source Enterprise ALM (GPL licence). Browing the page mentionning the
> projects using Sphinx http://sphinx-doc.org/examples.html, I realized Tuleap
> Open ALM is not included while the documentation of the project is managed
> thanks to Sphinx.Could you please add Tuleap Open ALM in the list of examples
> and the link to its doc: https://tuleap.net/doc/en/

Manon MIDY
manon.midy@enalean.com
Enalean
www.tuleap.org

docker pull miktex/miktex

> cd meta
> sphinx-quickstart

> make html

(tuto_javascript)  ~/projects/tuto_javascript > master > sphinx-quickstart

Welcome to the Sphinx 2.0.0b1 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]:

The project name will occur in several places in the built documentation.
> Project name: Tuto Javascript
> Author name(s): devops people
> Project release []: 0.1.0

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
http://sphinx-doc.org/config.html#confval-language.
> Project language [en]:

Creating file ./conf.py.
Creating file ./index.rst.
Creating file ./Makefile.
Creating file ./make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file ./index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# For conversion from markdown to html
import recommonmark.parser

# Add a source file parser for markdown
source_parsers = {
        '.md': 'recommonmark.parser.CommonMarkParser'
}

# Add type of source files
source_suffix = ['.rst', '.md']

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.intersphinx',
    'sphinx.ext.autosummary',
    'sphinx.ext.mathjax',
    'nbsphinx',
]

# Add type of source files
source_suffix = ['.rst', '.md', '.ipynb']

“Cheers for a great tool that actually makes programmers want to write documentation!”

#!/usr/bin/env python
#
# Copyright (C) 2012 Vinay Sajip. Licensed under the MIT license.
#
# Based on Roberto Alsina's 128-line web browser, see
#
# http://lateral.netmanagers.com.ar/weblog/posts/BB948.html
#
import json
import os
import subprocess
import sys
import tempfile
from urllib import pathname2url

import sip
sip.setapi("QString", 2)
sip.setapi("QVariant", 2)

from PyQt4 import QtGui,QtCore,QtWebKit, QtNetwork

settings = QtCore.QSettings("Vinay Sajip", "DocWatch")

class Watcher(QtCore.QThread):
        """
        A watcher which looks for source file changes, builds the documentation,
        and notifies the browser to refresh its contents
        """
        def run(self):
                self._stop = False
                watch_command = 'inotifywait -rq -e close_write --exclude \'"*.html"\' .'.split()
                make_command = 'make html'.split()
                while not self._stop:
                        # Perhaps should put notifier access in a mutex - not bothering yet
                        self.notifier = subprocess.Popen(watch_command)
                        self.notifier.wait()
                        if self._stop:
                                break
                        subprocess.call(make_command)
                        # Refresh the UI ...
                        self.parent().changed.emit()

        def stop(self):
                self._stop = True
                # Perhaps should put notifier access in a mutex - not bothering for now
                if self.notifier.poll() is None:    # not yet terminated ...
                        self.notifier.terminate()

class MainWindow(QtGui.QMainWindow):
        """
        A browser intended for viewing HTML documentation generated by Sphinx.
        """
        changed = QtCore.pyqtSignal()

        def __init__(self, url):
                QtGui.QMainWindow.__init__(self)
                self.sb=self.statusBar()

                self.pbar = QtGui.QProgressBar()
                self.pbar.setMaximumWidth(120)
                self.wb=QtWebKit.QWebView(loadProgress = self.pbar.setValue, loadFinished = self.pbar.hide, loadStarted = self.pbar.show, titleChanged = self.setWindowTitle)
                self.setCentralWidget(self.wb)

                self.tb=self.addToolBar("Main Toolbar")
                for a in (QtWebKit.QWebPage.Back, QtWebKit.QWebPage.Forward, QtWebKit.QWebPage.Reload):
                        self.tb.addAction(self.wb.pageAction(a))

                self.url = QtGui.QLineEdit(returnPressed = lambda:self.wb.setUrl(QtCore.QUrl.fromUserInput(self.url.text())))
                self.tb.addWidget(self.url)

                self.wb.urlChanged.connect(lambda u: self.url.setText(u.toString()))
                self.wb.urlChanged.connect(lambda: self.url.setCompleter(QtGui.QCompleter(QtCore.QStringList([QtCore.QString(i.url().toString()) for i in self.wb.history().items()]), caseSensitivity = QtCore.Qt.CaseInsensitive)))

                self.wb.statusBarMessage.connect(self.sb.showMessage)
                self.wb.page().linkHovered.connect(lambda l: self.sb.showMessage(l, 3000))

                self.search = QtGui.QLineEdit(returnPressed = lambda: self.wb.findText(self.search.text()))
                self.search.hide()
                self.showSearch = QtGui.QShortcut("Ctrl+F", self, activated = lambda: (self.search.show() , self.search.setFocus()))
                self.hideSearch = QtGui.QShortcut("Esc", self, activated = lambda: (self.search.hide(), self.wb.setFocus()))

                self.quit = QtGui.QShortcut("Ctrl+Q", self, activated = self.close)
                self.zoomIn = QtGui.QShortcut("Ctrl++", self, activated = lambda: self.wb.setZoomFactor(self.wb.zoomFactor()+.2))
                self.zoomOut = QtGui.QShortcut("Ctrl+-", self, activated = lambda: self.wb.setZoomFactor(self.wb.zoomFactor()-.2))
                self.zoomOne = QtGui.QShortcut("Ctrl+=", self, activated = lambda: self.wb.setZoomFactor(1))
                self.wb.settings().setAttribute(QtWebKit.QWebSettings.PluginsEnabled, True)

                self.sb.addPermanentWidget(self.search)
                self.sb.addPermanentWidget(self.pbar)

                self.load_settings()

                self.wb.load(url)
                self.watcher = Watcher(self)

                self.changed.connect(self.wb.reload)

                self.watcher.start()

        def load_settings(self):
                settings.beginGroup('mainwindow')
                pos = settings.value('pos')
                size = settings.value('size')
                if isinstance(pos, QtCore.QPoint):
                        self.move(pos)
                if isinstance(size, QtCore.QSize):
                        self.resize(size)
                settings.endGroup()

        def save_settings(self):
                settings.beginGroup('mainwindow')
                settings.setValue('pos', self.pos())
                settings.setValue('size', self.size())
                settings.endGroup()

        def closeEvent(self, event):
                self.save_settings()
                self.watcher.stop()

if __name__ == "__main__":
        if not os.path.isdir('_build'):
                # very simplistic sanity check. Works for me, as I generally use
                # sphinx-quickstart defaults
                print('You must run this application from a Sphinx directory containing _build')
                rc = 1
        else:
                app=QtGui.QApplication(sys.argv)
                path = os.path.join('_build', 'html', 'index.html')
                url = 'file:///' + pathname2url(os.path.abspath(path))
                url = QtCore.QUrl(url)
                wb=MainWindow(url)
                wb.show()
                rc = app.exec_()
        sys.exit(rc)

import clr
import os

from System.IO import FileSystemWatcher, NotifyFilters

stop = False

def on_change(source, e):
        global stop
        if not e.Name.endswith('.html'):
                stop = True
        print('%s: %s, stop = %s' % (e.FullPath, e.ChangeType, stop))

watcher = FileSystemWatcher(os.getcwd())
watcher.NotifyFilter = NotifyFilters.LastWrite | NotifyFilters.FileName
watcher.EnableRaisingEvents = True
watcher.IncludeSubdirectories = True
watcher.Changed += on_change
watcher.Created += on_change

while not stop:
        pass

#!/usr/bin/env python

import os

from fsevents import Observer, Stream

stop = False

def on_change(e):
        global stop
        path = e.name
        if os.path.isfile(path):
                if not path.endswith('.html'):
                        stop = True
        print('%s: %s, stop = %s' % (e.name, e.mask, stop))

observer = Observer()
observer.start()
stream = Stream(on_change, os.getcwd(), file_events=True)
observer.schedule(stream)
try:
        while not stop:
                pass
finally:
        observer.unschedule(stream)
        observer.stop()
        observer.join()

#!/bin/bash
## Automatically build Sphinx documentation upon file change
## Copyright (c) 2011 Samuele ~redShadow~ Santi - Under GPL

WORKDIR="$( dirname "$0" )"
while :; do
        ## Wait for changes
        inotifywait -e modify,create,delete -r "$WORKDIR"
        ## Make html documentation
        make -C "$WORKDIR" html
done

# Check for stylistic and formal issues in .rst and .py
# files included in the documentation.
#
# 01/2009, Georg Brandl

# TODO: - wrong versions in versionadded/changed
#       - wrong markup after versionchanged directive

$ pip install sphinxjp.themes.basicstrap

$ easy_install sphinxjp.themes.basicstrap

extensions = ['sphinxjp.themecore']
html_theme = 'basicstrap'

$ make html

pip install -U cloud_sptheme

Inline literal: ``literal text``.

External links are prefixed with an arrow: `<http://www.google.com>`_.

But email links are not prefixed: bob@example.com.

Issue tracker link: :issue:`5`.

extensions = [
    # http://pythonhosted.org/cloud_sptheme/index.html#extensions
    # https://bitbucket.org/ecollins/cloud_sptheme

    'cloud_sptheme.ext.issue_tracker',
]

# set path to issue tracker:
issue_tracker_url = "https://bitbucket.org/ecollins/cloud_sptheme/issue/{issue}"

.. note::
    This is a note.

.. warning::

    This is warning.

.. seealso::

    This is a "see also" message.

.. todo::

    This is a todo message.

    With some additional next on another line.

.. deprecated:: XXX This is a deprecation warning.

.. rst-class:: floater

.. note::
    This is a floating note.

extensions = [
    # http://pythonhosted.org/cloud_sptheme/index.html#extensions
    # https://bitbucket.org/ecollins/cloud_sptheme

    'cloud_sptheme.ext.table_styling',
]

.. table:: Normal Table

.. rst-class:: plain

.. table:: Plain Table (no row shading)

.. rst-class:: centered

.. table:: Centered Table

.. rst-class:: fullwidth

.. table:: Full Width Table

.. table:: Table Styling Extension
    :widths: 1 2 3
    :header-columns: 1
    :column-alignment: left center right
    :column-dividers: none single double single
    :column-wrapping: nnn

.. rst-class:: html-toggle

.. _toggle-test-link:

.. rst-class:: html-toggle expanded

.. rst-class:: emphasize-children

.. rst-class:: html-toggle

sphinx
cloud_sptheme

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
# -*- coding: utf-8 -*-
#
# Passlib documentation build configuration file, created by
# sphinx-quickstart on Mon Mar  2 14:12:06 2009.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.

import sys, os

options = os.environ.get("PASSLIB_DOCS", "").split(",")

#make sure passlib in sys.path
doc_root = os.path.abspath(os.path.join(__file__,os.path.pardir))
source_root = os.path.abspath(os.path.join(doc_root,os.path.pardir))
sys.path.insert(0, source_root)

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))

#building the docs requires the Cloud sphinx theme & extensions
# https://bitbucket.org/ecollins/cloud_sptheme
#which contains some sphinx extensions used by passlib
import cloud_sptheme as csp

#hack to make autodoc generate documentation from the correct class...
import passlib.utils.md4 as md4_mod
md4_mod.md4 = md4_mod._builtin_md4

# -- General configuration -----------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
    # standard sphinx extensions
    'sphinx.ext.autodoc',
    'sphinx.ext.todo',

    #add autdoc support for ReST sections in class/function docstrings
    'cloud_sptheme.ext.autodoc_sections',

    #adds extra ids & classes to genindex html, for additional styling
    'cloud_sptheme.ext.index_styling',

    #inserts toc into right hand nav bar (ala old style python docs)
    'cloud_sptheme.ext.relbar_toc',

    # add "issue" role
    'cloud_sptheme.ext.issue_tracker',
    ]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The suffix of source filenames.
source_suffix = '.rst'

# The encoding of source files.
source_encoding = 'utf-8'

# The master toctree document.
master_doc = 'contents'
index_doc = 'index'

# General information about the project.
project = u'Passlib'
copyright = u'2008-2012, Assurance Technologies, LLC'

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#

# version: The short X.Y version.
# release: The full version, including alpha/beta/rc tags.
from passlib import __version__ as release
version = csp.get_version(release)

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None

# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = [
    # disabling documentation of this until module is more mature.
    "lib/passlib.utils.compat.rst",

    # may remove this in future release
    "lib/passlib.utils.md4.rst",
]

# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None

# If true, '()' will be appended to :func: etc. cross-reference text.
add_function_parentheses = True

# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True

# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

# A list of ignored prefixes for module index sorting.
modindex_common_prefix = [ "passlib." ]

# -- Options for all output ---------------------------------------------------
todo_include_todos = "hide-todos" not in options
keep_warnings = "hide-warnings" not in options
issue_tracker_url = "gc:passlib"

# -- Options for HTML output ---------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
html_theme = 'redcloud'

# Theme options are theme-specific and customize the look and feel of a theme
# further.  For a list of options available for each theme, see the
# documentation.
if html_theme in ['cloud', 'redcloud']:
    html_theme_options = { "roottarget": index_doc, "collapsiblesidebar": True }
    if 'for-pypi' in options:
        html_theme_options['googleanalytics_id'] = 'UA-22302196-2'
        html_theme_options['googleanalytics_path'] = '/passlib/'
else:
    html_theme_options = {}
html_theme_options.update(issueicon=r'"\21D7"')

# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = [csp.get_theme_dir()]

# The name for this set of Sphinx documents.  If None, it defaults to
# "<project> v<release> documentation".
html_title = project + " v" + release + " Documentation"

# A shorter title for the navigation bar.  Default is the same as html_title.
html_short_title = project + " " + version + " Documentation"

# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
html_logo = os.path.join("_static", "masthead.png")

# The name of an image file (within the static path) to use as favicon of the
# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
html_favicon = "logo.ico"

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
html_last_updated_fmt = '%b %d, %Y'

# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
html_use_smartypants = True

# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}

# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}

# If false, no module index is generated.
#html_domain_indices = True

# If false, no index is generated.
#html_use_index = True

# If true, the index is split into individual pages for each letter.
#html_split_index = False

# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True

# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True

# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it.  The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''

# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None

# Output file base name for HTML help builder.
htmlhelp_basename = project + 'Doc'


# -- Options for LaTeX output --------------------------------------------------

# The paper size ('letter' or 'a4').
#latex_paper_size = 'letter'

# The font size ('10pt', '11pt' or '12pt').
#latex_font_size = '10pt'

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
  (index_doc, project + '.tex', project + u' Documentation',
   u'Assurance Technologies, LLC', 'manual'),
]

# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None

# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False

# If true, show page references after internal links.
#latex_show_pagerefs = False

# If true, show URL addresses after external links.
#latex_show_urls = False

# Additional stuff for the LaTeX preamble.
#latex_preamble = ''

# Documents to append as an appendix to all manuals.
#latex_appendices = []

# If false, no module index is generated.
#latex_domain_indices = True


# -- Options for manual page output --------------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
    (index_doc, project, project + u' Documentation',
     [u'Assurance Technologies, LLC'], 1)
]

Sujet:  Re: [sphinx-users] Where can I find a sphinx theme used in Python official documentation site?
Date :  Sat, 1 Feb 2014 04:52:34 -0800 (PST)
De :    Hiroki Watanabe <hwatanabe.japan@gmail.com>
Répondre à :    sphinx-users@googlegroups.com
Pour :  sphinx-users@googlegroups.com

sys.path.append(os.path.abspath('_themes'))
html_theme_path = ['_themes']
html_theme = 'pydoctheme'

html_theme_options = {
   'collapsiblesidebar': True,
   'sidebarbtncolor': '#eeeeee',
}

Hi,

I think this is the one:
http://hg.python.org/cpython/file/22e88355acd6/Doc/tools/sphinxext
<http://hg.python.org/cpython/file/22e88355acd6/Doc/tools/sphinxext>
However, I have not used it.

Regards,
--
Takayuki SHIMIZUKAWA
http://about.me/shimizukawa

[theme]
inherit = base theme
stylesheet = main CSS name
pygments_style = stylename

[options]
variable = default value

span.underlined {
    text-decoration: underline;
}

.. role:: underlined

:underlined:`test underlined`

From: Boris Kheyfets <kheyfboris@gmail.com>
Date: 2012/9/5
Subject: [sphinx-dev] Tip: vertical text
To: sphinx-dev@googlegroups.com

css:
span.vertical {
    writing-mode:tb-rl;
    -webkit-transform:rotate(270deg);
    -moz-transform:rotate(270deg);
    -o-transform: rotate(270deg);
    display:block;
    width:20px;
    height:20px;
}

rst:
.. role:: vertical

:vertical:`test`

I'm new to Sphinx, and I'd like to create a custom title page. I have
figured out how I can suppress the title page by adding 'maketitle': ' ',
in the conf.py file, but how do I replace it with a custom cover page?
And If I can, what format doe sit have to be in?

I'm using the "howto" sphinx template.

Georg Brandl <georg@python.org>
répondre à:  sphinx-users@googlegroups.com
à:   sphinx-users@googlegroups.com
date:    2 avril 2013 11:00
objet:   [sphinx-users] Re: Call for translation updates - Now on transifex

On 04/01/2013 12:26 PM, Georg Brandl wrote:
> Hi all,
>
> for the pending 1.2 release I'd like to update as many locales as possible.
> If you speak one of the languages that Sphinx supports and can spare the
> time, it would be great if you could look over the message catalog
> (sphinx.po) in your language at
> https://bitbucket.org/birkenfeld/sphinx/src/tip/sphinx/locale and open an
> issue/pull request with the necessary update or the new file.
>
> Thanks, Georg
>

class Starship:
    captain: str
    damage: int

This change also supports dataclasses (since Python 3.7) to be documented.

autodoc_typehints = "description"

def hello(name: str, age: int) -> str:
    """Hello world!

    :param name: Your name
    :param age: Your age
    :returns: greeting message
    """

///
/// <summary>
/// CR_RFID_DecouvrirLecteurs() Retourne la liste des lecteurs PS/SC de type
/// sous la forme d une liste de noms de la forme : "CodeRousseau RFID".
/// </summary>
/// <param name="ppListeNomsLecteursRFID"> [out] pointeur sur une liste de noms de lecteurs RFID.</param>.
/// <remarks>
/// </remarks>
/// <returns>
/// - COMMAND_SUCCESS: La commande s'est bien passee.
/// - COMMAND_FAILED: La commande a echoue.
/// </returns>
extern DWORD CR_RFID_DecouvrirLecteurs(ST_LIST_STRING **ppListeNomsLecteursRFID);

https://github.com/doxygen/doxygen

using System;

namespace IniParser
{
    /// <summary>
    /// Represents an error ococcurred while parsing data
    /// </summary>
    public class ParsingException : Exception
    {
        /// <summary>
        /// Initializes a new instance of the <see cref="ParsingException"/> class.
        /// </summary>
        public ParsingException(){ }

        /// <summary>
        /// Initializes a new instance of the <see cref="ParsingException"/> class.
        /// </summary>
        /// <param name="msg">The message describing the exception cause.</param>
        public ParsingException(string msg)
            : base(msg) { }

        /// <summary>
        /// Initializes a new instance of the <see cref="ParsingException"/> class.
        /// </summary>
        /// <param name="msg">The message describing the exception cause.</param>
        /// <param name="innerException">An inner exception.</param>
        public ParsingException(string msg, Exception innerException)
            : base(msg, innerException) { }
    }
}

using System;
using System.Collections;
using System.Collections.Generic;

namespace IniParser
{
    /// <summary>
    /// <para>Represents a collection of Keydata.</para>
    /// </summary>
    public class KeyDataCollection : ICloneable, IEnumerable<KeyData>
    {
        #region Initialization

        /// <summary>
        /// Initializes a new instance of the <see cref="KeyDataCollection"/> class.
        /// </summary>
        public KeyDataCollection()
        {
            _keyData = new Dictionary<string, KeyData>();
        }

        /// <summary>
        /// Initializes a new instance of the <see cref="KeyDataCollection"/> class
        /// from a previous instance of <see cref="KeyDataCollection"/>.
        /// </summary>
        /// <remarks>
        /// Data is deeply copied
        /// </remarks>
        /// <param name="ori">
        /// The instance of the <see cref="KeyDataCollection"/> class
        /// used to create the new instance.</param>
        public KeyDataCollection(KeyDataCollection ori)
        {
            _keyData = new Dictionary<string, KeyData>();
            foreach ( string key in _keyData.Keys )
                _keyData.Add(key, (KeyData)ori._keyData[key].Clone() );
        }

        #endregion

        #region Properties

        /// <summary>
        /// Gets or sets the value of a concrete key.
        /// </summary>
        /// <remarks>
        /// If we try to assign the value of a key which doesn't exists,
        /// a new key is added with the name and the value is assigned to it.
        /// </remarks>
        /// <param name="keyName">Name of the key</param>
        /// <returns>
        /// The string with key's value or null
        /// if the key was not found.
        /// </returns>
        public string this[string keyName]
        {
            get
            {
                if (_keyData.ContainsKey(keyName))
                    return _keyData[keyName].Value;

                return null;
            }

            set
            {
                if (!_keyData.ContainsKey(keyName))
                    return;

                _keyData[keyName].Value = value;

            }
        }

        /// <summary>
        /// Return the number of keys in the collection
        /// </summary>
        /// <value>An integer with the number of keys in the collection.</value>
        public int Count
        {
            get { return _keyData.Count; }
        }

        #endregion

        #region Public Methods

        /// <summary>
        /// Adds a new key with the specified name and empty value and comments
        /// </summary>
        /// <remarks>
        /// A valid key name is a string with NO blank spaces.
        /// </remarks>
        /// <param name="keyName">New key to be added.</param>
        /// <returns>
        /// <c>true</c> if a new empty key was added
        /// <c>false</c> otherwise.
        /// </returns>
        /// <exception cref="ArgumentException">If the key name is not valid.</exception>
        public bool AddKey(string keyName)
        {
            //Checks valid key name
            //if ( !Assert.StringHasNoBlankSpaces(keyName) )
            //    throw new ArgumentException("Key name is not valid");

            if ( !_keyData.ContainsKey(keyName) )
            {
                _keyData.Add(keyName, new KeyData(keyName));
                return true;
            }

            return false;
        }

        /// <summary>
        /// Adds a new key with the specified name and value and comments
        /// </summary>
        /// <remarks>
        /// A valid key name is a string with NO blank spaces.
        /// </remarks>
        /// <param name="keyName">New key to be added.</param>
        /// <param name="keyData">KeyData instance.</param>
        /// <returns>
        /// <c>true</c> if a new empty key was added
        /// <c>false</c> otherwise.
        /// </returns>
        /// <exception cref="ArgumentException">If the key name is not valid.</exception>
        public bool AddKey(string keyName, KeyData keyData)
        {
            if (AddKey(keyName))
            {
                _keyData[keyName] = keyData;
                return true;
            }

            return false;

        }

        /// <summary>
        /// Adds a new key with the specified name and value and comments
        /// </summary>
        /// <remarks>
        /// A valid key name is a string with NO blank spaces.
        /// </remarks>
        /// <param name="keyName">New key to be added.</param>
        /// <param name="keyValue">Value associated to the kyy.</param>
        /// <returns>
        /// <c>true</c> if a new empty key was added
        /// <c>false</c> otherwise.
        /// </returns>
        /// <exception cref="ArgumentException">If the key name is not valid.</exception>
        public bool AddKey(string keyName, string keyValue)
        {
            if (AddKey(keyName))
            {
                _keyData[keyName].Value = keyValue;
                return true;
            }

            return false;

        }

        /// <summary>
        /// Retrieves the data for a specified key given its name
        /// </summary>
        /// <param name="keyName">Name of the key to retrieve.</param>
        /// <returns>
        /// A <see cref="KeyData"/> instance holding
        /// the key information or <c>null</c> if the key wasn't found.
        /// </returns>
        public KeyData GetKeyData(string keyName)
        {
            if (_keyData.ContainsKey(keyName))
                return _keyData[keyName];
            return null;
        }

        /// <summary>
        /// Sets the key data associated to a specified key.
        /// </summary>
        /// <param name="data">The new <see cref="KeyData"/> for the key.</param>
        public void SetKeyData(KeyData data)
        {
            if (data != null)
            {
                if (_keyData.ContainsKey(data.KeyName))
                    RemoveKey(data.KeyName);

                AddKey(data.KeyName, data);
            }
        }

        /// <summary>
        /// Gets if a specifyed key name exists in the collection.
        /// </summary>
        /// <param name="keyName">Key name to search</param>
        /// <returns><c>true</c> if a key with the specified name exists in the collectoin
        /// <c>false</c> otherwise</returns>
        public bool ContainsKey(string keyName)
        {
            return _keyData.ContainsKey(keyName);
        }

        /// <summary>
        /// Deletes a previously existing key, including its associated data.
        /// </summary>
        /// <param name="keyName">The key to be removed.</param>
        /// <returns>
        /// <c>true</c> if a key with the specified name was removed
        /// <c>false</c> otherwise.
        /// </returns>
        public bool RemoveKey(string keyName)
        {
            return _keyData.Remove(keyName);
        }

        #endregion

        #region IEnumerable<KeyData> Members

        /// <summary>
        /// Allows iteration througt the collection.
        /// </summary>
        /// <returns>A strong-typed IEnumerator </returns>
        public IEnumerator<KeyData> GetEnumerator()
        {
            foreach ( string key in _keyData.Keys )
                yield return _keyData[key];
        }

        #region IEnumerable Members

        /// <summary>
        /// Implementation needed
        /// </summary>
        /// <returns>A weak-typed IEnumerator.</returns>
        IEnumerator IEnumerable.GetEnumerator()
        {
            return _keyData.GetEnumerator();
        }

        #endregion

        #endregion

        #region ICloneable Members


        /// <summary>
        /// Creates a new object that is a copy of the current instance.
        /// </summary>
        /// <returns>
        /// A new object that is a copy of this instance.
        /// </returns>
        public object Clone()
        {
            return new KeyDataCollection(this);
        }

        #endregion

        #region Non-public Members

        /// <summary>
        /// Collection of KeyData for a given section
        /// </summary>
        private readonly Dictionary<string, KeyData> _keyData;

        #endregion

    }
}

GENERATE_DOCSET   = YES
DISABLE_INDEX     = YES
SEARCHENGINE      = NO
GENERATE_TREEVIEW = NO

mkdir $HOME/src
cd $HOME/src
git clone https://github.com/gohugoio/hugo.git
cd hugo
go install

git clone git@github.com:gohugoio/hugo.git

git clone git://github.com/jgm/pandoc.git

git submodule update --init

#!/bin/sh
git submodule update --init

chmod +x .git/hooks/post-merge

pandoc README.md -o README.rst

$ pip install pdoc3

$ pdoc your_project

<!DOCTYPE html>
<html>
  <head>
    <title>ReDoc</title>
    <!-- needed for adaptive design -->
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">

    <!--
    ReDoc doesn't change outer page styles
    -->
    <style>
      body {
        margin: 0;
        padding: 0;
      }
    </style>
  </head>
  <body>
    <redoc spec-url='http://petstore.swagger.io/v2/swagger.json'></redoc>
    <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
  </body>
</html>

yarn add redoc

npm install redoc --save

<script src="https://cdn.jsdelivr.net/npm/redoc/bundles/redoc.standalone.js"> </script>

<script src="node_modules/redoc/bundles/redoc.standalone.js"> </script>

<redoc spec-url="url/to/your/spec"></redoc>

npm i react react-dom mobx@^4.2.0 styled-components

import { RedocStandalone } from 'redoc';

<RedocStandalone specUrl="url/to/your/spec"/>

<RedocStandalone spec={/* spec as an object */}/>

<RedocStandalone
  specUrl="http://rebilly.github.io/RebillyAPI/openapi.json"
  options={{
    nativeScrollbars: true,
    theme: { colors: { primary { main: '#dd5522' } } },
  }}
/>

<RedocStandalone
  specUrl="http://rebilly.github.io/RebillyAPI/openapi.json"
  onLoaded={error => {
    if (!error) {
      console.log('Yay!');
    }
  }}
/>

docker pull redocly/redoc
docker run -p 8080:80 redocly/redoc

docker run -p 8080:80 -e SPEC_URL=https://api.example.com/openapi.json redocly/redoc

Redoc.init(specOrSpecUrl, options, element, callback?)

Redoc.init('http://petstore.swagger.io/v2/swagger.json', {
  scrollYOffset: 50
}, document.getElementById('redoc-container'))

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
image: python:3.8-slim

pages:
  script:
  - pip install -r requirements.txt
  - sphinx-build -d _build/doctrees . _build/html
  - mv _build/html public
  artifacts:
    paths:
    - public
  only:
  - master

pipenv lock -r > requirements.txt

total 200
 4 drwxr-xr-x 10 pvergain doc  4096 mai   21 12:53 ./
 4 drwxrwxr-x 14 pvergain doc  4096 mai   20 19:41 ../
 4 drwxr-xr-x  4 pvergain doc  4096 mai   21 11:31 _build/
68 -rw-r--r--  1 pvergain doc 66507 mai   16 22:28 charac-more.png
 4 drwxr-xr-x  7 pvergain doc  4096 mai   16 22:28 cli/
 8 -rw-r--r--  1 pvergain doc  5786 mai   21 11:23 conf.py
 4 drwxr-xr-x  4 pvergain doc  4096 mai   16 22:28 devel/
 4 drwxr-xr-x 12 pvergain doc  4096 mai   21 11:29 documentation/
 4 drwxr-xr-x  8 pvergain doc  4096 mai   21 14:31 .git/
 4 -rw-r--r--  1 pvergain doc   140 mai   20 18:40 .gitignore
 4 -rw-r--r--  1 pvergain doc   212 mai   16 22:28 .gitlab-ci.yml
 4 -rw-r--r--  1 pvergain doc   920 mai   21 12:53 index.rst
 4 -rw-r--r--  1 pvergain doc   651 mai   16 22:28 Makefile
16 -rw-r--r--  1 pvergain doc 15811 mai   21 14:31 objects.inv
 4 -rw-r--r--  1 pvergain doc   158 mai   16 22:28 Pipfile
 8 -rw-r--r--  1 pvergain doc  6388 mai   21 11:12 Pipfile.lock
 4 -rw-r--r--  1 pvergain doc   327 mai   21 12:26 README.md
 4 -rw-r--r--  1 pvergain doc   344 mai   20 18:39 requirements.txt
32 -rw-r--r--  1 pvergain doc 29330 mai   16 22:28 small-globe.png
 4 drwxr-xr-x  2 pvergain doc  4096 mai   16 22:28 _static/
 4 drwxr-xr-x  4 pvergain doc  4096 mai   16 22:28 _themes/
 4 drwxr-xr-x  4 pvergain doc  4096 mai   16 22:29 .venv/

git clone http://github.com/rtfd/readthedocs.org.git

$ pip install Flask-Funnel

$ pip install Flask-Funnel==dev

$ git clone git://github.com/rehandalal/flask-funnel.git
$ mkvirtualenv flaskfunnel
$ python setup.py develop
$ pip install -r requirements.txt

$ python setup.py test

make develop
make documentation

Django
Pillow
Markdown

pip install markdown

boards/models.py (view complete file contents)

from django.db import models
from django.utils.html import mark_safe
from markdown import markdown

class Post(models.Model):
    # ...

    def get_message_as_markdown(self):
        return mark_safe(markdown(self.message, safe_mode='escape'))

<form method="POST" novalidate>

1
2
3
4
5
6
7
 class Post(models.Model):
     title = models.CharField(max_length=100)
     content = models.TextField()
     date_posted = models.DateTimeField(default=timezone.now)
     last_modified = models.DateTimeField(auto_now=True)
     author = models.ForeignKey('users.CustomUser', on_delete=models.CASCADE)
     slug = models.SlugField(null=False, unique=True)

extensions = ["sphinx.ext.intersphinx", "recommonmark"]
source_suffix = {
    ".rst": "restructuredtext",
    ".md": "markdown",
}

[tool.poetry]
name = "tuto_django"
version = "0.1.0"
description = "Django tutorial"
authors = ["Patrick Vergain <pvergain@pm.me>"]
license = "MIT"

[tool.poetry.dependencies]
python = "3.8.2"
sphinx = "*"
recommonmark = "*"

[tool.poetry.dev-dependencies]

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
#
# Configuration file for the Sphinx documentation builder.
# http://www.sphinx-doc.org/en/stable/config

from datetime import datetime

project = "Tuto Documentation"
author = "DevOps people"
version = "0.1.0"
release = version
now = datetime.now()
today = f"{now.year}-{now.month:02}-{now.day:02} {now.hour:02}H{now.minute:02}"
copyright = f"2009-{now.year}, {author}"
source_suffix = {
    ".rst": "restructuredtext",
    ".md": "markdown",
}
master_doc = "index"
language = None
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".venv"]
html_theme = "bizstyle"
pygments_style = "sphinx"
extensions = ["sphinx.ext.intersphinx", "recommonmark", "sphinx_tabs.tabs"]
intersphinx_mapping = {
    "python": ("https://docs.python.org/", None),
    "official_sphinx": ("http://www.sphinx-doc.org/", None),
    "https://gdevops.gitlab.io/tuto_python/": None,
    "https://gdevops.gitlab.io/tuto_django/": None,
    "docker": ("https://gdevops.gitlab.io/tuto_docker/", None),
    "https://gdevops.gitlab.io/tuto_cli/": None,
    "https://gdevops.gitlab.io/tuto_build/": None,
    "https://gdevops.gitlab.io/tuto_kubernetes/": None,
    "http://blockdiag.com/en/": None,
}
extensions = extensions + ["sphinx.ext.todo"]
todo_include_todos = True




###########################################################################
#          auto-created readthedocs.org specific configuration            #
###########################################################################


#
# The following code was added during an automated build on readthedocs.org
# It is auto created and injected for every build. The result is based on the
# conf.py.tmpl file found in the readthedocs.org codebase:
# https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl
#


import importlib
import sys
import os.path
from six import string_types

from sphinx import version_info

# Get suffix for proper linking to GitHub
# This is deprecated in Sphinx 1.3+,
# as each page can have its own suffix
if globals().get('source_suffix', False):
    if isinstance(source_suffix, string_types):
        SUFFIX = source_suffix
    elif isinstance(source_suffix, (list, tuple)):
        # Sphinx >= 1.3 supports list/tuple to define multiple suffixes
        SUFFIX = source_suffix[0]
    elif isinstance(source_suffix, dict):
        # Sphinx >= 1.8 supports a mapping dictionary for multiple suffixes
        SUFFIX = list(source_suffix.keys())[0]  # make a ``list()`` for py2/py3 compatibility
    else:
        # default to .rst
        SUFFIX = '.rst'
else:
    SUFFIX = '.rst'

# Add RTD Static Path. Add to the end because it overwrites previous files.
if not 'html_static_path' in globals():
    html_static_path = []
if os.path.exists('_static'):
    html_static_path.append('_static')

# Add RTD Theme only if they aren't overriding it already
using_rtd_theme = (
    (
        'html_theme' in globals() and
        html_theme in ['default'] and
        # Allow people to bail with a hack of having an html_style
        'html_style' not in globals()
    ) or 'html_theme' not in globals()
)
if using_rtd_theme:
    theme = importlib.import_module('sphinx_rtd_theme')
    html_theme = 'sphinx_rtd_theme'
    html_style = None
    html_theme_options = {}
    if 'html_theme_path' in globals():
        html_theme_path.append(theme.get_html_theme_path())
    else:
        html_theme_path = [theme.get_html_theme_path()]

if globals().get('websupport2_base_url', False):
    websupport2_base_url = 'https://readthedocs.org/websupport'
    websupport2_static_url = 'https://assets.readthedocs.org/static/'


#Add project information to the template context.
context = {
    'using_theme': using_rtd_theme,
    'html_theme': html_theme,
    'current_version': "latest",
    'version_slug': "latest",
    'MEDIA_URL': "https://media.readthedocs.org/",
    'STATIC_URL': "https://assets.readthedocs.org/static/",
    'PRODUCTION_DOMAIN': "readthedocs.org",
    'versions': [
    ("latest", "/en/latest/"),
    ("stable", "/en/stable/"),
    ("0.3.0", "/en/0.3.0/"),
    ("0.1.0", "/en/0.1.0/"),
    ],
    'downloads': [ 
    ("pdf", "//devopstutodoc.readthedocs.io/_/downloads/en/latest/pdf/"),
    ("html", "//devopstutodoc.readthedocs.io/_/downloads/en/latest/htmlzip/"),
    ],
    'subprojects': [ 
    ],
    'slug': 'devopstutodoc',
    'name': u'devopstuto_doc',
    'rtd_language': u'en',
    'programming_language': u'py',
    'canonical_url': 'https://devopstutodoc.readthedocs.io/en/latest/',
    'analytics_code': '',
    'single_version': False,
    'conf_py_path': '/',
    'api_host': 'https://readthedocs.org',
    'github_user': 'None',
    'github_repo': 'None',
    'github_version': 'master',
    'display_github': False,
    'bitbucket_user': 'None',
    'bitbucket_repo': 'None',
    'bitbucket_version': 'master',
    'display_bitbucket': False,
    'gitlab_user': 'gdevops',
    'gitlab_repo': 'tuto_documentation',
    'gitlab_version': 'master',
    'display_gitlab': True,
    'READTHEDOCS': True,
    'using_theme': (html_theme == "default"),
    'new_theme': (html_theme == "sphinx_rtd_theme"),
    'source_suffix': SUFFIX,
    'ad_free': False,
    'user_analytics_code': '',
    'global_analytics_code': 'UA-17997319-1',
    'commit': '79bea070',
}




if 'html_context' in globals():
    
    html_context.update(context)
    
else:
    html_context = context

# Add custom RTD extension
if 'extensions' in globals():
    # Insert at the beginning because it can interfere
    # with other extensions.
    # See https://github.com/rtfd/readthedocs.org/pull/4054
    extensions.insert(0, "readthedocs_ext.readthedocs")
else:
    extensions = ["readthedocs_ext.readthedocs"]

# Add External version warning banner to the external version documentation
if 'branch' == 'external':
    extensions.insert(1, "readthedocs_ext.external_version_warning")

project_language = 'en'

# User's Sphinx configurations
language_user = globals().get('language', None)
latex_engine_user = globals().get('latex_engine', None)
latex_elements_user = globals().get('latex_elements', None)

# Remove this once xindy gets installed in Docker image and XINDYOPS
# env variable is supported
# https://github.com/rtfd/readthedocs-docker-images/pull/98
latex_use_xindy = False

chinese = any([
    language_user in ('zh_CN', 'zh_TW'),
    project_language in ('zh_CN', 'zh_TW'),
])

japanese = any([
    language_user == 'ja',
    project_language == 'ja',
])

if chinese:
    latex_engine = latex_engine_user or 'xelatex'

    latex_elements_rtd = {
        'preamble': '\\usepackage[UTF8]{ctex}\n',
    }
    latex_elements = latex_elements_user or latex_elements_rtd
elif japanese:
    latex_engine = latex_engine_user or 'platex'

rst2html.py -stg test.txt test.html

I've always pronounced LaTeX "lah-tech," but today I heard its developer
Leslie Lamport pronounce it "lay-tech.

sudo apt-get install latexmk

/usr/bin/latexmk

hh -decompile dossier_cible nom_de_fichier.chm

"A universal convention supplies all of maintainability, clarity, consistency,
and a foundation for good programming habits too. What it doesn't do is
insist that you follow it against your will. That's Python !"

—Tim Peters on comp.lang.python, 2001-06-16

pip install blockdiag

Collecting blockdiag
Downloading https://files.pythonhosted.org/packages/e6/37/a3a4d09c8cbe16b303ed75fd07381e5460b37a25fe247645f2251477887a/blockdiag-1.5.4-py2.py3-none-any.whl (2.7MB)
|████████████████████████████████| 2.7MB 1.1MB/s
Collecting Pillow (from blockdiag)
Downloading https://files.pythonhosted.org/packages/c1/e6/ce127fa0ac17775bc7887c432ffe945c49ae141f01b477b7cd5e63b16bb5/Pillow-6.0.0-cp37-cp37m-manylinux1_x86_64.whl (2.0MB)
|████████████████████████████████| 2.0MB 1.6MB/s
Collecting webcolors (from blockdiag)
Downloading https://files.pythonhosted.org/packages/1d/44/c4902683be73beba20afd299705e11f0a753a01cc7f9d6a070841848605b/webcolors-1.8.1-py2.py3-none-any.whl
Collecting funcparserlib (from blockdiag)
Downloading https://files.pythonhosted.org/packages/cb/f7/b4a59c3ccf67c0082546eaeb454da1a6610e924d2e7a2a21f337ecae7b40/funcparserlib-0.3.6.tar.gz
Requirement already satisfied: setuptools in ./.pyenv/versions/3.7.3/lib/python3.7/site-packages (from blockdiag) (40.8.0)
Installing collected packages: Pillow, webcolors, funcparserlib, blockdiag
Running setup.py install for funcparserlib ... done
Successfully installed Pillow-6.0.0 blockdiag-1.5.4 funcparserlib-0.3.6 webcolors-1.8.1

pip install seqdiag

Collecting seqdiag
  Downloading https://files.pythonhosted.org/packages/0d/45/c4afb6fb9bb7c16e28d4bedaab15195792fd49448edde0f202e850f15764/seqdiag-0.9.6-py2.py3-none-any.whl (2.6MB)
         |████████████████████████████████| 2.6MB 1.3MB/s
Requirement already satisfied: blockdiag>=1.5.0 in ./.pyenv/versions/3.7.3/lib/python3.7/site-packages (from seqdiag) (1.5.4)
Requirement already satisfied: webcolors in ./.pyenv/versions/3.7.3/lib/python3.7/site-packages (from blockdiag>=1.5.0->seqdiag) (1.8.1)
Requirement already satisfied: funcparserlib in ./.pyenv/versions/3.7.3/lib/python3.7/site-packages (from blockdiag>=1.5.0->seqdiag) (0.3.6)
Requirement already satisfied: Pillow in ./.pyenv/versions/3.7.3/lib/python3.7/site-packages (from blockdiag>=1.5.0->seqdiag) (6.0.0)
Requirement already satisfied: setuptools in ./.pyenv/versions/3.7.3/lib/python3.7/site-packages (from blockdiag>=1.5.0->seqdiag) (40.8.0)
Installing collected packages: seqdiag
Successfully installed seqdiag-0.9.6

pip install actdiag

Collecting actdiag
Downloading https://files.pythonhosted.org/packages/39/13/4b7b1d738cea26fbe80d1a5546628115d10b0f02880be2b724cc8004f5db/actdiag-0.5.4-py2.py3-none-any.whl (2.6MB)
|████████████████████████████████| 2.6MB 1.2MB/s
Requirement already satisfied: blockdiag>=1.5.0 in ./.pyenv/versions/3.7.3/lib/python3.7/site-packages (from actdiag) (1.5.4)
Requirement already satisfied: setuptools in ./.pyenv/versions/3.7.3/lib/python3.7/site-packages (from actdiag) (40.8.0)
Requirement already satisfied: webcolors in ./.pyenv/versions/3.7.3/lib/python3.7/site-packages (from blockdiag>=1.5.0->actdiag) (1.8.1)
Requirement already satisfied: Pillow in ./.pyenv/versions/3.7.3/lib/python3.7/site-packages (from blockdiag>=1.5.0->actdiag) (6.0.0)
Requirement already satisfied: funcparserlib in ./.pyenv/versions/3.7.3/lib/python3.7/site-packages (from blockdiag>=1.5.0->actdiag) (0.3.6)
Installing collected packages: actdiag
Successfully installed actdiag-0.5.4

pip install nwdiag

Collecting nwdiag
  Downloading https://files.pythonhosted.org/packages/8e/06/42e672cc4b0efddd40f0c0de412dda7c29f8a971afb54b3d77579c28aa29/nwdiag-1.0.4-py2.py3-none-any.whl (7.7MB)
         |████████████████████████████████| 7.7MB 1.5MB/s
Requirement already satisfied: setuptools in ./.pyenv/versions/3.7.3/lib/python3.7/site-packages (from nwdiag) (40.8.0)
Requirement already satisfied: blockdiag>=1.5.0 in ./.pyenv/versions/3.7.3/lib/python3.7/site-packages (from nwdiag) (1.5.4)
Requirement already satisfied: Pillow in ./.pyenv/versions/3.7.3/lib/python3.7/site-packages (from blockdiag>=1.5.0->nwdiag) (6.0.0)
Requirement already satisfied: funcparserlib in ./.pyenv/versions/3.7.3/lib/python3.7/site-packages (from blockdiag>=1.5.0->nwdiag) (0.3.6)
Requirement already satisfied: webcolors in ./.pyenv/versions/3.7.3/lib/python3.7/site-packages (from blockdiag>=1.5.0->nwdiag) (1.8.1)
Installing collected packages: nwdiag
Successfully installed nwdiag-1.0.4

Sujet:  [Wikitech-l] Recycling wikitech-announce for tech contributors
Date :  Sat, 13 Apr 2013 12:23:21 -0700
De :    Quim Gil <qgil@wikimedia.org>
Répondre à :    Wikimedia developers <wikitech-l@lists.wikimedia.org>
Organisation :  Wikimedia Foundation
Pour :  Wikimedia developers <wikitech-l@lists.wikimedia.org>

--
Quim Gil
Technical Contributor Coordinator @ Wikimedia Foundation
http://www.mediawiki.org/wiki/User:Qgil

[django-wiki@googlegroups.com](https://groups.google.com/d/forum/django-wiki)

[twitter:djangowiki](https://twitter.com/djangowiki)

from wiki.urls import get_pattern as get_wiki_pattern
from django_notify.urls import get_pattern as get_notify_pattern
urlpatterns += patterns('',
    (r'^notify/', get_notify_pattern()),
    (r'', get_wiki_pattern())
)


Value	Name	French Message
0x8130F001L	CR_E_FAILED	Une vérification de cohérence interne a échoué.
0x8130F002L	CR_E_TIMEOUT	Le délai a expiré.
0x8130F003L	CR_E_SEND_DATA_FAILED	L’envoi des données a échoué.
0x8130F004L	CR_E_OPEN_PORT_FAILED	L’ouverture du port COM a échoué.
0x8130F005L	CR_E_CLOSE_PORT_FAILED	La fermeture du port COM a échoué.
0x8130F006L	CR_E_BAD_SYNCHRO	Erreur de synchronisation avec la base.
0x8130F007L	CR_E_BAD_ADDRESS	Mauvaise adresse.
0x8130F008L	CR_E_BAD_SIZE	Taille incorrecte.
0x8130F009L	CR_E_BAD_CHANNEL	Mauvais canal.
0x8130F00AL	CR_E_BAD_STATUS	Mauvais statut retourné par la base.
0x8130F00BL	CR_E_OPEN_FILE_FAILED	Ouverture du fichier a échoué.

Header1	Header2	Header3
Row 1	Row 1	Row 1
Row 2	Row 2	Row 2
Row 3	Row 3	Row 3

Header1	Header2	Header3
Row 1	Row 1	Row 1
Row 2	Row 2	Row 2
Row 3	Row 3	Row 3

Header1	Header2	Header3
Row 1	Row 1	Row 1
Row 2	Row 2	Row 2
Row 3	Row 3	Row 3

Header1	Header2	Header3
Row 1	Row 1	Row 1
Row 2	Row 2	Row 2
Row 3	Row 3	Row 3

Description	In	Out	Balance
Travel		230.00	-230.00
Fees		400.00	-630.00
Grant	700.00		70.00
Train Fare		70.00	0.00

Header row, column 1 (header rows optional)	Header 2	Header 3	Header 4
body row 1, column 1	column 2	column 3	column 4
body row 2	…	…

Condition	Decision
comparison score >= threshold	Match
comparison score < threshold	Non-Match

Shapes	Description
Square	Four sides of equal length, 90 degree angles
Rectangle	Four sides, 90 degree angles

Error type	Definition	Impact
False Match	Comparison decision of “match” for a biometric probe and a biometric reference that are from different fingers	System security lack
False Non-Match	Comparison decision of “non-match” for a biometric probe and a biometric reference that are from the same finger	User inconvenience

Dependency	License
github.com/BurntSushi/locker	The Unlicense
github.com/BurntSushi/toml	MIT License
github.com/PuerkitoBio/purell	BSD 3-Clause “New” or “Revised” License
github.com/PuerkitoBio/urlesc	BSD 3-Clause “New” or “Revised” License
github.com/alecthomas/chroma	MIT License
github.com/bep/debounce	MIT License
github.com/bep/gitmap	MIT License
github.com/bep/go-tocss	MIT License
github.com/chaseadamsio/goorgeous	MIT License
github.com/cpuguy83/go-md2man	MIT License
github.com/danwakefield/fnmatch	BSD 2-Clause “Simplified” License
github.com/disintegration/imaging	MIT License
github.com/dlclark/regexp2	MIT License
github.com/eknkc/amber	MIT License
github.com/fsnotify/fsnotify	BSD 3-Clause “New” or “Revised” License
github.com/gobwas/glob	MIT License
github.com/gorilla/websocket	BSD 2-Clause “Simplified” License
github.com/hashicorp/go-immutable-radix	Mozilla Public License 2.0
github.com/hashicorp/golang-lru	Mozilla Public License 2.0
github.com/hashicorp/hcl	Mozilla Public License 2.0
github.com/jdkato/prose	MIT License
github.com/kyokomi/emoji	MIT License
github.com/magiconair/properties	BSD 2-Clause “Simplified” License
github.com/markbates/inflect	MIT License
github.com/mattn/go-isatty	MIT License
github.com/mattn/go-runewidth	MIT License
github.com/miekg/mmark	Simplified BSD License
github.com/mitchellh/hashstructure	MIT License
github.com/mitchellh/mapstructure	MIT License
github.com/muesli/smartcrop	MIT License
github.com/nicksnyder/go-i18n	MIT License
github.com/olekukonko/tablewriter	MIT License
github.com/pelletier/go-toml	MIT License
github.com/pkg/errors	BSD 2-Clause “Simplified” License
github.com/russross/blackfriday	Simplified BSD License
github.com/shurcooL/sanitized_anchor_name	MIT License
github.com/spf13/afero	Apache License 2.0
github.com/spf13/cast	MIT License
github.com/spf13/cobra	Apache License 2.0
github.com/spf13/fsync	MIT License
github.com/spf13/jwalterweatherman	MIT License
github.com/spf13/nitro	Apache License 2.0
github.com/spf13/pflag	BSD 3-Clause “New” or “Revised” License
github.com/spf13/viper	MIT License
github.com/tdewolff/minify	MIT License
github.com/tdewolff/parse	MIT License
github.com/wellington/go-libsass	Apache License 2.0
github.com/yosssi/ace	MIT License
golang.org/x/image	BSD 3-Clause “New” or “Revised” License
golang.org/x/net	BSD 3-Clause “New” or “Revised” License
golang.org/x/sync	BSD 3-Clause “New” or “Revised” License
golang.org/x/sys	BSD 3-Clause “New” or “Revised” License
golang.org/x/text	BSD 3-Clause “New” or “Revised” License
gopkg.in/yaml.v2	Apache License 2.0

✨	Feature
🐛	Bug
🎀	UI improvement
📚	Documentation
🐎	Performance
🎨	Code style
🔥	Code removal
🔨	Refactoring
☔	Tests
🔒	Security issue
⬆	Dependency upgrade
🚨	Fix CI build
🧹	Housekeeping
📦	Packaging
🚀	Release
🗺	Translations

ReDoc Release	OpenAPI Specification
2.0.0-alpha.x	3.0, 2.0
1.19.x	2.0
1.18.x	2.0
1.17.x	2.0

Documentation tutorial¶

Documentation news¶

Hypermodern Python Chapter 5: Documentation (2020-01-29) by https://twitter.com/cjolowicz/¶

Write the docs news¶

Mindshare¶

Documentation generators¶

Sphinx¶

Sphinx development (Development Guide)¶

sphinx applications¶

Editing sphinx doc on the web¶

Sphinx to github¶

sphinx-wiki¶

reStructuredText Sphinx documentation¶

sphinx markup¶

sphinx code¶

toctree¶

Paragraphs¶

Image¶

Source Code¶

include¶

code-block (pygments, highlight)¶

rest Tables¶

Sphinx Sections¶

Explicit Markup¶

Sphinx Directives¶

Sphinx Footnotes¶

Comments¶

Source encoding¶

sidebar¶

Gotchas¶

sphinx.ext. Sphinx extensions¶

sphinx.ext.autosummary (Generate autodoc summaries)¶

Contributed sphinx extensions¶

Doxygen contributed extensions¶

javasphinx extension¶

sphinx odt2sphinx extension¶

rstspreadsheet sphinx extension¶

rst2qhc (Qt)¶

sphinx report¶

sphinx UML extensions¶

Sphinx i18n¶

Sphinx builders¶

Sphinx usage¶

Sphinx people¶

Tools for building sphinx¶

Qt program¶

Automatically-build-sphinx-documentation¶

Rst lint¶

Sphinx themes¶