Piccolo Theme¶

A clean and modern theme for Sphinx.

Setup¶

Install Sphinx¶

pip install sphinx

Create a docs folder within your project, and run sphinx-quickstart.

mkdir docs
cd docs
sphinx-quickstart

sphinx-quickstart will scaffold your documentation for you.

Install Piccolo Theme¶

pip install piccolo_theme

Find the conf.py file that Sphinx generated for you. Within that set the following value:

html_theme = 'piccolo_theme'

Building your docs¶

Sphinx creates a Makefile in your docs folder. To generate some HTML docs, run the following in the same directory as your Makefile:

make html

Within your docs folder, Sphinx will have generated some HTML files in _build/html.

To serve these files using Python, you can use:

python -m http.server --directory _build/html/

Now open up http://localhost:8000 in your browser to see your beautiful docs!

Configuration¶

`html_short_title`¶

If you have a really long project name, you may prefer something shorter to appear in the navigation bar. Specify this using html_short_title in conf.py:

# conf.py

# By default the project value is used in the nav bar.
project = 'My Extra Special Amazing Docs'

# If specified, this will be used in the nav bar instead.
html_short_title = "Amazing Docs"

`html_logo`¶

If you want to use a logo in the nav bar instead of text, specify html_logo in conf.py:

# conf.py

# It can either be a path to an image, relative to conf.py:
html_logo = './static/logo.png'

# Or it can be a URL:
html_logo = 'https://awesome.com/static/logo.png'

`pygments_style`¶

We use the default Pygments theme for syntax highlighting of code blocks. It gives good results out of the box (including great dark mode support).

If you’d prefer to use a different Pygments style, you can specify it using pygments_style in conf.py:

# conf.py

pygments_style = "stata-dark"

Dark Mode¶

When switching to dark mode, we automatically apply our own dark mode styles to code blocks. If you’d like to disable this behaviour, see dark_mode_code_blocks.

Theme specific¶

`source_url`¶

If specified, a link is shown in the nav bar to the source code.

# conf.py

html_theme_options = {
    "source_url": 'https://github.com/piccolo-orm/piccolo_theme/'
}

We try and detect if the URL points to GitHub or GitLab, and show the correct icon. However, if you’re using a self hosted version of GitHub or GitLab on a custom URL, you can explicitly tell the theme which icon to use:

# conf.py

html_theme_options = {
    "source_url": 'https://self-hosted.foo.com/',
    "source_icon": "gitlab"
}

The available options for source_icon are:

generic
github
gitlab

`banner_text`¶

If this is provided then a banner is shown at the top of the page. It’s useful for important announcements.

# conf.py

html_theme_options = {
    # Note how we can include links:
    "banner_text": 'We just launched a newletter, <a href="https://mynewsletter.com/">please subscribe</a>!'
}

`banner_hiding`¶

This controls how the banner behaves when hidden. The options are 'temporary' (the default) or 'permanent'.

If 'temporary', when a user hides the banner they can still reopen it again. This is useful if you want to store important information in the banner, which the user may need to refer to again. For example:

# conf.py

html_theme_options = {
    "banner_text": 'Please be aware of security issue XYZ!',
    "banner_hiding": "temporary"
}

If 'permanent', when a user hides the banner it disappears permanently. This is useful when the banner contains information which the user is unlikely to need again. For example:

# conf.py

html_theme_options = {
    "banner_text": 'Welcome to our amazing documentation!',
    "banner_hiding": "permanent"
}

Note

If you configure a different banner_text value in the future, then the banner will appear again, even if the user has previously hidden it.

`dark_mode_code_blocks`¶

When switching to dark mode, we apply our own custom CSS styles to code blocks. This gives a great dark mode experience out of the box.

However, if you’ve specified a custom Pygments theme (see pygments_style), and you want to use that theme for both light mode and dark mode, you can disable our custom dark mode styles:

# conf.py

html_theme_options = {
    "dark_mode_code_blocks": False,
}

`show_theme_credit`¶

At the bottom of the page is a very small link which says Styled using the Piccolo Theme.

This helps grow awareness of the project, and attract new contributors.

You can hide this if required:

# conf.py

html_theme_options = {
    "show_theme_credit": False
}

If hiding it, please consider supporting us in a different way.

Help¶

The best place to get help is on our GitHub discussions page.

It’s also a great place to share any feedback you have about the theme, and how we can make improvements.

Support Us¶

You can help us in many ways:

Sharing the project with others
Leaving feedback
Starring the repo on GitHub
Making improvements to the theme by making a pull request
Buying our book about documentation and Sphinx

Thanks! 🙏

About¶

This theme was created to document Piccolo and sister projects.

Here’s a live example of it being used:

https://piccolo-orm.readthedocs.io/en/latest/

Contributing¶

Styles¶

We use Sass as a CSS preprocessor. The styles live in src/sass.

To modify the styles, first install Sass:

npm install -g sass

Then run:

./scripts/build-styles.sh

This will automatically rebuild your CSS when it detects a change in the Sass files.

Running the docs¶

By running Piccolo Theme’s docs you can verify that your changes look OK.

First install the requirements:

pip install -r requirements/doc-requirements.txt

Then launch a web server using the following script:

./scripts/run-docs.sh

It auto reloads when it detects changes to the documentation or theme files.

Demo¶

This is used to demonstrate various features, and also for testing.

Autodoc¶

class piccolo_theme.snippets.Column(null: bool = False, primary_key: bool = False, unique: bool = False, index: bool = False, required: bool = False, help_text: Optional[str] = None, choices: Optional[Type[Enum]] = None, db_column_name: Optional[str] = None, secret: bool = False, **kwargs)¶

All other columns inherit from Column. Don’t use it directly.

The following arguments apply to all column types:

Parameters

null – Whether the column is nullable.
primary_key – If set, the column is used as a primary key.
default – The column value to use if not specified by the user.
unique – If set, a unique contraint will be added to the column.
index – Whether an index is created for the column, which can improve the speed of selects, but can slow down inserts.
index_method – If index is set to True, this specifies what type of index is created.
required – This isn’t used by the database - it’s to indicate to other tools that the user must provide this value. Example uses are in serialisers for API endpoints, and form fields.
help_text – This provides some context about what the column is being used for. For example, for a Decimal column called value, it could say 'The units are millions of dollars'. The database doesn’t use this value, but tools such as Piccolo Admin use it to show a tooltip in the GUI.
choices – An optional Enum - when specified, other tools such as Piccolo Admin will render the available options in the GUI.
db_column_name –
If specified, you can override the name used for the column in the database. The main reason for this is when using a legacy database, with a problematic column name (for example 'class', which is a reserved Python keyword). Here’s an example:
```
class MyTable(Table):
    class_ = Varchar(db_column_name="class")

>>> await MyTable.select(MyTable.class_)
[{'id': 1, 'class': 'test'}]
```
This is an advanced feature which you should only need in niche situations.

secret –

If secret=True is specified, it allows a user to automatically omit any fields when doing a select query, to help prevent inadvertent leakage of sensitive data.

class Band(Table):
    name = Varchar()
    net_worth = Integer(secret=True)

>>> await Band.select(exclude_secrets=True)
[{'name': 'Pythonistas'}]

Breathe¶

class CppClass¶

CppClass class.

Details about CppClass.

Public Functions

const char *member_function(char, int)¶

A member function.

Parameters

c – a character.
n – an integer.

Throws

std::out_of_range – parameter is out of range.

Returns

a character pointer.

void cpp_function(int *a, int *b, int *c)¶

Doing important things with parameter directions.

Parameters

a – [out] output
b – [in] input
c – [inout] input but gets rewritten

void c_function(int *a, int *b, int *c)¶

Doing important things with parameter directions.

Parameters

a – [out] output
b – [in] input
c – [inout] input but gets rewritten

Tables¶

Table 1¶

Name	Drives
Alice	True
Bob	True
Curtis	False

Table 2¶

Header 1	Header 2	Header 3
body row 1	column 2	column 3
body row 2	Cells may span columns. And several paragraphs.
body row 3	Cells may span rows.	Cells contain blocks.
body row 4	Cells may span rows.	Cells contain blocks.

Data definitions¶

Python: A great programming language.
Sphinx: A powerful documentation tool.

Lists¶

Unordered List¶

Python
Rust
Javascript

Ordered List¶

Python
Rust
Javascript

Admonitions¶

Warning

This is a warning!

Error

This is an error!

Hint

This is a hint!

Note

This is a note!

A custom admonition

This is my custom admonition!

Changes¶

0.14.0¶

When switching to dark mode, we automatically apply our own custom dark mode styles to code blocks.

This gives a great experience out of the box. However, if someone uses their own Pygments theme, they might want to use that theme in both light mode, and dark mode. They can now do so, using the dark_mode_code_blocks option.

# conf.py

html_theme_options = {
    "dark_mode_code_blocks": False
}

0.13.0¶

A logo can now be used in the nav bar, instead of text.

# conf.py

# Relative to conf.py:
html_logo = './path/to/logo.png'

# Or an absolute URL:
html_logo = 'https://awesome.com/static/logo.png'

Thanks to @are-scenic for adding this.

0.12.0¶

You can now specify the source code URL, and it will show in the nav bar.

# conf.py

html_theme_options = {
    "source_url": 'https://github.com/piccolo-orm/piccolo_theme/'
}

The icon is inferred automatically based on the URL (in the above example, we show the GitHub logo). You can explicitly set the icon if you prefer:

# conf.py

html_theme_options = {
    "source_url": 'https://self-hosted.foo.com/',
    "source_icon": "gitlab"
}

0.11.1¶

Minor style fix on search page.

0.11.0¶

Fixed some styles in Sphinx v5.

0.10.2¶

Drop Python 3.7 specific syntax.

0.10.1¶

Fix typo in setup.py.

0.10.0¶

Added support for Python 3.6, as many Ubuntu systems will still be using that version, and Sphinx still supports it. Thanks to @oncilla for reporting this issue.

0.9.0¶

Improved the appearance of autodoc output for C files (when using breathe). Courtesy @thijsmie.

0.8.1¶

Changed the arrow symbols - they didn’t look great on mobile.

0.8.0¶

Added spacing between sections, so it’s not necessary to add horizontal dividers any more.

My Heading
==========

Section 1
---------

Some content

-------------------------------------------

Section 2
---------

Some content

We can now just do:

My Heading
==========

Section 1
---------

Some content


Section 2
---------

Some content

Other minor changes:

Using unicode triangle character instead of < for some links
Plain admonitions are now styled properly:

.. admonition:: A custom admonition

   This is my custom admonition!

0.7.1¶

Improvements to the notification feature - it was causing too many browser reflow operations.

0.7.0¶

A notification can now be shown at the top of each page.

# conf.py
html_theme_options = {
    "banner_text": 'Welcome to our amazing documentation!',
    "banner_hiding": "permanent"
}

This involved quite a few CSS changes - please clear your browser cache if anything appears broken.

0.6.0¶

If html_short_title is in conf.py then this is used in the nav bar instead of the full project title.

0.5.1¶

Fixed dark mode styles - some elements weren’t visible. Thanks to @alorence for reporting this issue.

0.5.0¶

Added table styles.

0.4.0¶

Improved the appearance of autodoc output for C++ files (when using breathe). Courtesy @thijsmie.

0.3.0¶

Added dark mode.

0.2.5¶

Improved search styles.

0.2.4¶

Added missing requirements.txt file to manifest. Thanks to @moorepants for reporting this.

0.2.3¶

Make the page contents text smaller when the right hand sidebar is hidden.

0.2.2¶

Fix missing static files.

0.2.1¶

Fix missing static files.

0.2.0¶

Improved the main header on mobile - the search bar is replaced with a search icon. Also increased the size of the touch targets for showing / hiding the right sidebar, for easier use on mobile. See PR 7.

Piccolo Theme¶

Setup¶

Install Sphinx¶

Install Piccolo Theme¶

Building your docs¶

Configuration¶

html_short_title¶

html_logo¶

pygments_style¶

Dark Mode¶

Theme specific¶

source_url¶

banner_text¶

banner_hiding¶

dark_mode_code_blocks¶

show_theme_credit¶

Help¶

Support Us¶

About¶

Contributing¶

Styles¶

Running the docs¶

Demo¶

Autodoc¶

Breathe¶

Tables¶

Table 1¶

Table 2¶

Data definitions¶

Lists¶

Unordered List¶

Ordered List¶

Admonitions¶

Changes¶

0.14.0¶

0.13.0¶

0.12.0¶

0.11.1¶

0.11.0¶

0.10.2¶

0.10.1¶

0.10.0¶

0.9.0¶

0.8.1¶

0.8.0¶

0.7.1¶

0.7.0¶

0.6.0¶

0.5.1¶

0.5.0¶

0.4.0¶

0.3.0¶

0.2.5¶

0.2.4¶

0.2.3¶

0.2.2¶

0.2.1¶

0.2.0¶

`html_short_title`¶

`html_logo`¶

`pygments_style`¶

`source_url`¶

`banner_text`¶

`banner_hiding`¶

`dark_mode_code_blocks`¶

`show_theme_credit`¶