Sphinx extension¶
Document your config¶
Having a well-documented config greatly improves the user experience of your application. If you are documenting your Python project using Sphinx (which you should), you can use Cyra’s build-in Sphinx extension to automatically generate documentation for your config.
Configure Sphinx¶
To use the Cyradoc Sphinx extension, you have to specify it in your conf.py
.
Make sure Cyra as well as all dependencies required to import your config class
are installed in the Python environment from which you are running Sphinx.
extensions = [
'cyra.cyradoc',
]
Cyradoc directive¶
To generate documentation for your config, use the .. cyradoc::
directive
with the path to the config class specified.
.. cyradoc:: mymodule.config.Config
Cyradoc will insert your config as toml-formatted code blocks (see the example below).
If you have added 1_getting_started:Docstrings to your config, Cyradoc splits your config into multiple blocks and adds the docstrings in between.
If your config class has a docstring it will be added to the top, as well.
If you dont want to include any docstrings, use the :no-docstrings:
flag.
.. cyradoc:: mymodule.config.Config
:no-docstrings:
Example¶
Here I created a sample config class for a fictional application.
Using the .. cyradoc::
Sphinx directive
a documented version of the config file can be inserted into
any Sphinx documentation.
Specify your welcome message here
msg = "Hello World" # Cyra says hello
Configure your database here.
Warning
Keep your credentials secret!
[DATABASE] # SQL Database settings
server = "192.168.1.1" # DB server address
port = 1443 # SQL port (default: 1443)
username = "admin" # Credentials
password = "my_secret_password"
enabled = true # DB connection enabled
Here you can add all the servers you want to observe.
Example:
alpha
beta
[SERVERS] # Servers to be monitored
[SERVERS.alpha]
ip = "10.0.0.1" # Server IP address
enable = true # Set to false to disable server access
priority = 1 # Server priority
users = ["ThetaDev", "Clary"] # Users to be handled
[SERVERS.beta]
ip = "10.0.0.2" # Server IP address
enable = false # Set to false to disable server access
priority = 2 # Server priority
users = ["ThetaDev"] # Users to be handled
You can have arbitrary dictionaries as config options, too.
[DICT] # Arbitrary dictionary
key1 = "V1"
key2 = "V2"
key3 = "V3"
[DICT.keyA]
keyA1 = "VA1"
keyA2 = "VA2"
[DICT.keyB]
keyB1 = "VB1"
keyB2 = "VB2"
Source¶
import cyra
class Config(cyra.Config):
"""
Here I created a sample config class for a fictional application.
Using the ``.. cyradoc::`` Sphinx directive
a documented version of the config file can be inserted into
any Sphinx documentation.
"""
builder = cyra.ConfigBuilder()
builder.docstring('Specify your welcome message here')
builder.comment('Cyra says hello')
msg = builder.define('msg', 'Hello World')
builder.docstring('''
Configure your **database** here.
.. warning::
Keep your credentials secret!
''')
builder.comment('SQL Database settings')
builder.push('DATABASE')
builder.comment('DB server address')
server = builder.define('server', '192.168.1.1')
builder.comment('SQL port (default: 1443)')
port = builder.define('port', 1443)
builder.comment('Credentials')
user = builder.define('username', 'admin')
pwd = builder.define('password', 'my_secret_password')
builder.comment('DB connection enabled')
dben = builder.define('enabled', True)
builder.pop()
builder.docstring('''
Here you can add all the servers you want to observe.
**Example:**
- alpha
- beta
''')
builder.comment('Servers to be monitored')
builder.push('SERVERS')
builder.push('alpha')
builder.comment('Server IP address')
ip_a = builder.define('ip', '10.0.0.1')
builder.comment('Set to false to disable server access')
en_a = builder.define('enable', True)
builder.comment('Server priority')
prio_a = builder.define('priority', 1)
builder.comment('Users to be handled')
users_a = builder.define('users', ['ThetaDev', 'Clary'])
builder.pop()
builder.push('beta')
builder.comment('Server IP address')
ip_b = builder.define('ip', '10.0.0.2')
builder.comment('Set to false to disable server access')
en_b = builder.define('enable', False)
builder.comment('Server priority')
prio_b = builder.define('priority', 2)
builder.comment('Users to be handled')
users_b = builder.define('users', ['ThetaDev'])
builder.pop(2)
builder.docstring('''
You can have arbitrary dictionaries as config options, too.
''')
builder.comment('Arbitrary dictionary')
xdict = builder.define('DICT', {
'key1': 'V1',
'key2': 'V2',
'key3': 'V3',
'keyA': {
'keyA1': 'VA1',
'keyA2': 'VA2',
},
'keyB': {
'keyB1': 'VB1',
'keyB2': 'VB2',
},
})