From 9848c927b389232adede0edcf0a4b6d8acab0a63 Mon Sep 17 00:00:00 2001 From: ArthurFlageul Date: Mon, 29 Jan 2024 14:45:19 +0100 Subject: [PATCH] =?UTF-8?q?update:=20readme=20=F0=9F=94=92?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 34 +++++++++++++ README.rst | 143 ----------------------------------------------------- 2 files changed, 34 insertions(+), 143 deletions(-) create mode 100644 README.md delete mode 100644 README.rst diff --git a/README.md b/README.md new file mode 100644 index 0000000000..6652eb1149 --- /dev/null +++ b/README.md @@ -0,0 +1,34 @@ +# 🔒 Former Aiven Documentation + +> [!IMPORTANT] +> This repository used to be the main documentation of Aiven. +> +> The content has been migrated to https://github.com/aiven/aiven-docs. + +## Building the docs + +1. We recommend using a [virtual environment](https://docs.python.org/3/library/venv.html): + + ```bash + python3 -m venv venv + ``` + +1. Activate your virtual environment: + + ```bash + source venv/bin/activate + ``` + +1. Install the dependencies: + + ```bash + pip install -r requirements.txt + ``` + +1. Build a local preview: + + ```bash + make livehtml + ``` + +See the output on [http://localhost:8000](http://localhost:8000). diff --git a/README.rst b/README.rst deleted file mode 100644 index d2a75fa44d..0000000000 --- a/README.rst +++ /dev/null @@ -1,143 +0,0 @@ -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 <.github/vale/README.rst>`_. 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 `_ - -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 ` 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 `_.