Skip to content
This repository has been archived by the owner on Jan 29, 2024. It is now read-only.
/ devportal Public archive

Resources for users of the projects on the Aiven platform

License

Notifications You must be signed in to change notification settings

aiven/devportal

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Jan 10, 2024
c82bfa0 · Jan 10, 2024
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Aiven Documentation

This is the source for the Aiven documentation at https://docs.aiven.io. We are working to move all of our technical documentation to this platform, and welcome issues and pull requests from everyone.

It is Python-based, with content in ReStructuredText (rst) and rendered by Sphinx.

Contributing

Check the CONTRIBUTING guide for details on how to create content for these docs. You will find the style guide, pull request process and templates for the various content types there.

Local Development

We recommend using a virtual environment like venv:

python3 -m venv venv

Activate your virtual environment using the activate script for your environment:

source venv/bin/activate

Install the dependencies:

pip install -r requirements.txt

Start the HTML version with:

make livehtml

Your preview should be at http://localhost:8000 (if anything doesn't seem to re-render well, the navigation seems particularly unreliable, try make clean and then make livehtml again).

> If you are working on the templates, try the additional make livehtmlall command. This disables sphinx's incremental build and also observes changes to the assets, so it's slower but more like a full rebuild when things change.

Windows users

Replace all make commands with ./make - this uses the make.bat file instead of Makefile but the functionality should be equivalent.

Running build tasks locally

To run the spell check locally, you will need to have Vale installed on your computer and available on your path.

  • Check links: make linkcheck
  • Check spelling and usage: make spell

For documentation on how we use Vale, see our Vale README. This also explains how to add new words to the dictionary, or alter the things that Vale checks.

Installing Vale

The Vale installation page has instructions for all platforms including docker; this will be updated if the approach changes between versions.

On Fedora (F34), here's a tip for installing Vale (current version 2.16) (without a package manager) using the following::

package=$(curl -s https://api.github.com/repos/errata-ai/vale/releases/latest \
| jq -r ' .assets[] | select(.name | contains("Linux"))'); output=$(mktemp -d); \
echo $package | jq -r '.browser_download_url' | xargs curl -L --output-dir $output -O; \
echo $package | jq -r '.name' | sed -r "s#(.*)#$output/\1#g" | xargs cat \
| tar xzf - -C $output; cp -v $output/vale $HOME/bin

Then add $HOME/bin to $PATH (e.g. in .bashrc, where vale is downloaded to via the above command)

Alternatively, use snap or brew: https://vale.sh/docs/vale-cli/installation/

Navigation structure

The left-hand navigation menu is driven by a plugin called Sphinx external TOC. You can find our structure in _toc.yml.

Formatting tips

Here's an incomplete but helpful collection of tips for formatting your content on Aiven Docs.

Links

Links are different depending on whether they are external links, links pointing to a specific page on the site, or links pointing to a specific anchor or label.

External links are used for external hyperlinks:

`ReStructuredText <https://docutils.sourceforge.io/rst.html>`_

If you get the warning Duplicate target name, because of multiple links with the same label, use an anonymous link .

To link to another page on the site, use the :doc: role:

Use the :doc:`cli` for scriptable, repeatable actions with Aiven

The :doc: role uses the page title but if you want to change the link text, you can do so:

With an :doc:`API <api/index>` you can build any integration you choose

To create a label to link to a particular section (this is also useful if renaming titles that might have links pointing to the old wording), place the label immediately before the section heading:

.. _tools_cli_tips_tricks:

Tips and Tricks
===============

Then you can refer to the label with a :ref: entry:

There are some :ref:`_tools_cli_tips_tricks` to assist you.

Diagrams

Diagrams use sphinxcontrib-mermaid and mermaid.js syntax.

Sections and panels

We're using sphinx-panels for the card layout you see on the homepage and in a few other places. Please use sparingly :)

Code samples

Code samples should be autodetected (using pygments) and also will automatically include the "click to copy" button in the top right thanks to sphinx-copybutton.

Do not include a $ before a command that the user should run, because it will get copied into the user's clipboard and cause the command to fail (this has been a common standard in the past).

Search

Docs search

Aiven Docs uses custom OpenSearch based search.

Aiven.io search

Aiven.io global search are powered by Algolia and it includes index from Aiven Docs pages. Using the python script that creates, parses and adds the Docs pages to Algolia index (scripts/index_algolia.py)

License

This work is licensed under a Creative Commons Attribution 4.0 International License.