This is work in progress.
The site will be a place to hold all our developer-facing content.
It is Python-based, with content in ReStructuredText (rst) and rendered by Sphinx.
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).
Replace all make commands with ./make - this uses the make.bat file instead of Makefile but the functionality should be equivalent.
Please make changes! Even small fixes are very welcome. The content is in the docs/ folder, in ReStructuredText.
When you open a pull request, you will get a preview of your changes (useful if you or someone you want to show the work to does not have the tool set up locally). The process also runs some spelling and link checking tasksi so please check the output of the build if it fails.
To run the spell check locally, you will need to have [Vale](https://github.com/errata-ai/vale) installed on your computer and available on your path.
- Check links:
make linkcheck - Check spelling:
make spell
If the spellchecker is rejecting words that are valid (such as technology terms), double check the spelling and capitalisation, then add the word to .github/styles/Vocab/Docs/accept.txt.
The left-hand navigation menu is driven by a plugin called Sphinx external TOC. You can find our structure in _toc.yml.
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>`_
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 use sphinxcontrib-mermaid and mermaid.js syntax.
This work is licensed under a Creative Commons Attribution 4.0 International License.