Mercurial > libervia-backend
annotate doc/conf.py @ 4340:ea72364131d5 default tip @
doc (components): Update Email Gateway documentation:
A section has been added to explain how attachments are handled.
fix 453
| author | Goffi <goffi@goffi.org> |
|---|---|
| date | Tue, 03 Dec 2024 00:53:18 +0100 |
| parents | c0bb4b3fdccf |
| children |
| rev | line source |
|---|---|
| 3137 | 1 |
| 2946 | 2 # |
| 3 # Configuration file for the Sphinx documentation builder. | |
| 4 # | |
| 5 # This file does only contain a selection of the most common options. For a | |
| 6 # full list see the documentation: | |
| 7 # http://www.sphinx-doc.org/en/master/config | |
| 8 | |
| 9 # -- Path setup -------------------------------------------------------------- | |
| 10 | |
| 11 # If extensions (or modules to document with autodoc) are in another directory, | |
| 12 # add these directories to sys.path here. If the directory is relative to the | |
| 13 # documentation root, use os.path.abspath to make it absolute, like shown here. | |
| 14 # | |
|
3605
62e81b1058f8
doc: activate `autodoc` extension + extension to adapt Libervia docstring style to autodoc
Goffi <goffi@goffi.org>
parents:
3505
diff
changeset
|
15 import os |
|
62e81b1058f8
doc: activate `autodoc` extension + extension to adapt Libervia docstring style to autodoc
Goffi <goffi@goffi.org>
parents:
3505
diff
changeset
|
16 import sys |
| 2946 | 17 import os.path |
| 18 import re | |
| 4102 | 19 from libervia.backend import __version__ |
| 2946 | 20 |
| 21 | |
|
3605
62e81b1058f8
doc: activate `autodoc` extension + extension to adapt Libervia docstring style to autodoc
Goffi <goffi@goffi.org>
parents:
3505
diff
changeset
|
22 sys.path.insert(0, os.path.abspath("./_ext")) |
|
62e81b1058f8
doc: activate `autodoc` extension + extension to adapt Libervia docstring style to autodoc
Goffi <goffi@goffi.org>
parents:
3505
diff
changeset
|
23 |
|
62e81b1058f8
doc: activate `autodoc` extension + extension to adapt Libervia docstring style to autodoc
Goffi <goffi@goffi.org>
parents:
3505
diff
changeset
|
24 |
| 2946 | 25 # -- Project information ----------------------------------------------------- |
| 26 | |
|
4077
d6837db456fd
refactoring: fix names in doc following modules hierarchy refactoring
Goffi <goffi@goffi.org>
parents:
3990
diff
changeset
|
27 project = 'Libervia Backend' |
|
d6837db456fd
refactoring: fix names in doc following modules hierarchy refactoring
Goffi <goffi@goffi.org>
parents:
3990
diff
changeset
|
28 copyright = '2019-2023 Libervia' |
| 3479 | 29 author = 'Libervia team' |
| 2946 | 30 |
| 4102 | 31 version = __version__ |
| 2946 | 32 |
| 33 | |
| 34 # -- General configuration --------------------------------------------------- | |
| 35 | |
|
3951
4b8776eb6826
doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:
Goffi <goffi@goffi.org>
parents:
3605
diff
changeset
|
36 |
|
4b8776eb6826
doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:
Goffi <goffi@goffi.org>
parents:
3605
diff
changeset
|
37 rst_prolog = """ |
|
4b8776eb6826
doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:
Goffi <goffi@goffi.org>
parents:
3605
diff
changeset
|
38 .. |e2e_arg| replace:: |
|
4b8776eb6826
doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:
Goffi <goffi@goffi.org>
parents:
3605
diff
changeset
|
39 To publish an end-to-end encrypted item, you can use the ``-e, --encrypt`` flag, and |
|
4b8776eb6826
doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:
Goffi <goffi@goffi.org>
parents:
3605
diff
changeset
|
40 share secrets with :ref:`libervia-cli_pubsub_secret`. Please read |
|
4b8776eb6826
doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:
Goffi <goffi@goffi.org>
parents:
3605
diff
changeset
|
41 :ref:`pubsub-encryption` for more details. |
|
3966
9f85369294f3
doc (encryption, cli): pubsub signing documentation:
Goffi <goffi@goffi.org>
parents:
3951
diff
changeset
|
42 |
|
3975
c4418949aa37
doc (encryption, cli): document Pubsub Targeted Encryption:
Goffi <goffi@goffi.org>
parents:
3966
diff
changeset
|
43 .. |pte_arg| replace:: |
|
c4418949aa37
doc (encryption, cli): document Pubsub Targeted Encryption:
Goffi <goffi@goffi.org>
parents:
3966
diff
changeset
|
44 You can encrypt a single item to targeted entities with the ``--encrypt-for`` flag (not |
|
c4418949aa37
doc (encryption, cli): document Pubsub Targeted Encryption:
Goffi <goffi@goffi.org>
parents:
3966
diff
changeset
|
45 to be confused with ``--encrypt`` which is used when a whole node is encrypted). Please |
|
c4418949aa37
doc (encryption, cli): document Pubsub Targeted Encryption:
Goffi <goffi@goffi.org>
parents:
3966
diff
changeset
|
46 read :ref:`pubsub-encryption` for more details. |
|
c4418949aa37
doc (encryption, cli): document Pubsub Targeted Encryption:
Goffi <goffi@goffi.org>
parents:
3966
diff
changeset
|
47 |
|
3966
9f85369294f3
doc (encryption, cli): pubsub signing documentation:
Goffi <goffi@goffi.org>
parents:
3951
diff
changeset
|
48 .. |sign_arg| replace:: |
|
9f85369294f3
doc (encryption, cli): pubsub signing documentation:
Goffi <goffi@goffi.org>
parents:
3951
diff
changeset
|
49 To cryptographically sign an item, you can use the ``-X, --sign`` flag (a mnemonic way |
|
9f85369294f3
doc (encryption, cli): pubsub signing documentation:
Goffi <goffi@goffi.org>
parents:
3951
diff
changeset
|
50 to remember the short option is to think of a cross made as a signature on a document). |
|
9f85369294f3
doc (encryption, cli): pubsub signing documentation:
Goffi <goffi@goffi.org>
parents:
3951
diff
changeset
|
51 Signature can then be checked with :ref:`libervia-cli_pubsub_signature`. Please read |
|
9f85369294f3
doc (encryption, cli): pubsub signing documentation:
Goffi <goffi@goffi.org>
parents:
3951
diff
changeset
|
52 :ref:`pubsub-encryption` for more details. |
|
9f85369294f3
doc (encryption, cli): pubsub signing documentation:
Goffi <goffi@goffi.org>
parents:
3951
diff
changeset
|
53 |
|
3951
4b8776eb6826
doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:
Goffi <goffi@goffi.org>
parents:
3605
diff
changeset
|
54 """ |
|
4b8776eb6826
doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:
Goffi <goffi@goffi.org>
parents:
3605
diff
changeset
|
55 |
| 2946 | 56 # If your documentation needs a minimal Sphinx version, state it here. |
| 57 # | |
| 58 # needs_sphinx = '1.0' | |
| 59 | |
| 60 # Add any Sphinx extension module names here, as strings. They can be | |
| 61 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom | |
| 62 # ones. | |
| 63 extensions = [ | |
|
3605
62e81b1058f8
doc: activate `autodoc` extension + extension to adapt Libervia docstring style to autodoc
Goffi <goffi@goffi.org>
parents:
3505
diff
changeset
|
64 "sphinx.ext.autodoc", |
|
62e81b1058f8
doc: activate `autodoc` extension + extension to adapt Libervia docstring style to autodoc
Goffi <goffi@goffi.org>
parents:
3505
diff
changeset
|
65 "docstring" |
| 2946 | 66 ] |
| 67 | |
| 68 # Add any paths that contain templates here, relative to this directory. | |
| 69 templates_path = ['.templates'] | |
| 70 | |
| 71 # The suffix(es) of source filenames. | |
| 72 # You can specify multiple suffix as a list of string: | |
| 73 # | |
| 74 # source_suffix = ['.rst', '.md'] | |
| 75 source_suffix = '.rst' | |
| 76 | |
| 77 # The master toctree document. | |
| 78 master_doc = 'index' | |
| 79 | |
| 80 # The language for content autogenerated by Sphinx. Refer to documentation | |
| 81 # for a list of supported languages. | |
| 82 # | |
| 83 # This is also used if you do content translation via gettext catalogs. | |
| 84 # Usually you set "language" from the command line for these cases. | |
|
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3975
diff
changeset
|
85 language = "en" |
| 2946 | 86 |
| 87 # List of patterns, relative to source directory, that match files and | |
| 88 # directories to ignore when looking for source files. | |
| 89 # This pattern also affects html_static_path and html_extra_path. | |
| 90 exclude_patterns = [u'.build', 'Thumbs.db', '.DS_Store'] | |
| 91 | |
| 92 # The name of the Pygments (syntax highlighting) style to use. | |
| 93 pygments_style = None | |
| 94 | |
| 95 | |
| 96 # -- Options for HTML output ------------------------------------------------- | |
| 97 | |
| 98 # The theme to use for HTML and HTML Help pages. See the documentation for | |
| 99 # a list of builtin themes. | |
| 100 # | |
| 101 html_theme = 'alabaster' | |
| 102 | |
| 103 # Theme options are theme-specific and customize the look and feel of a theme | |
| 104 # further. For a list of options available for each theme, see the | |
| 105 # documentation. | |
| 106 # | |
| 107 # html_theme_options = {} | |
| 108 | |
| 109 # Add any paths that contain custom static files (such as style sheets) here, | |
| 110 # relative to this directory. They are copied after the builtin static files, | |
| 111 # so a file named "default.css" will overwrite the builtin "default.css". | |
| 112 html_static_path = ['.static'] | |
| 113 | |
| 114 # Custom sidebar templates, must be a dictionary that maps document names | |
| 115 # to template names. | |
| 116 # | |
| 117 # The default sidebars (for documents that don't match any pattern) are | |
| 118 # defined by theme itself. Builtin themes are using these templates by | |
| 119 # default: ``['localtoc.html', 'relations.html', 'sourcelink.html', | |
| 120 # 'searchbox.html']``. | |
| 121 # | |
| 122 # html_sidebars = {} | |
| 123 | |
| 124 | |
| 125 # -- Options for HTMLHelp output --------------------------------------------- | |
| 126 | |
| 127 # Output file base name for HTML help builder. | |
| 128 htmlhelp_basename = 'SalutToidoc' | |
| 129 | |
| 130 | |
| 131 # -- Options for LaTeX output ------------------------------------------------ | |
| 132 | |
| 133 latex_elements = { | |
| 134 # The paper size ('letterpaper' or 'a4paper'). | |
| 135 # | |
| 136 # 'papersize': 'letterpaper', | |
| 137 | |
| 138 # The font size ('10pt', '11pt' or '12pt'). | |
| 139 # | |
| 140 # 'pointsize': '10pt', | |
| 141 | |
| 142 # Additional stuff for the LaTeX preamble. | |
| 143 # | |
| 144 # 'preamble': '', | |
| 145 | |
| 146 # Latex figure (float) alignment | |
| 147 # | |
| 148 # 'figure_align': 'htbp', | |
| 149 } | |
| 150 | |
| 151 # Grouping the document tree into LaTeX files. List of tuples | |
| 152 # (source start file, target name, title, | |
| 153 # author, documentclass [howto, manual, or own class]). | |
| 154 latex_documents = [ | |
| 3505 | 155 (master_doc, 'SalutToi.tex', u'Libervia Documentation', |
| 156 u'Libervia team', 'manual'), | |
| 2946 | 157 ] |
| 158 | |
| 159 | |
| 160 # -- Options for manual page output ------------------------------------------ | |
| 161 | |
| 162 # One entry per manual page. List of tuples | |
| 163 # (source start file, name, description, authors, manual section). | |
| 164 man_pages = [ | |
| 3505 | 165 (master_doc, 'saluttoi', u'Libervia Documentation', |
| 2946 | 166 [author], 1) |
| 167 ] | |
| 168 | |
| 169 | |
| 170 # -- Options for Texinfo output ---------------------------------------------- | |
| 171 | |
| 172 # Grouping the document tree into Texinfo files. List of tuples | |
| 173 # (source start file, target name, title, author, | |
| 174 # dir menu entry, description, category) | |
| 175 texinfo_documents = [ | |
| 3505 | 176 (master_doc, 'SalutToi', u'Libervia Documentation', |
| 2946 | 177 author, 'SalutToi', 'One line description of project.', |
| 178 'Miscellaneous'), | |
| 179 ] | |
| 180 | |
| 181 | |
| 182 # -- Options for Epub output ------------------------------------------------- | |
| 183 | |
| 184 # Bibliographic Dublin Core info. | |
| 185 epub_title = project | |
| 186 | |
| 187 # The unique identifier of the text. This can be a ISBN number | |
| 188 # or the project homepage. | |
| 189 # | |
| 190 # epub_identifier = '' | |
| 191 | |
| 192 # A unique identification for the text. | |
| 193 # | |
| 194 # epub_uid = '' | |
| 195 | |
| 196 # A list of files that should not be packed into the epub file. | |
| 197 epub_exclude_files = ['search.html'] | |
| 198 | |
| 199 | |
| 200 # -- Extension configuration ------------------------------------------------- |