From 09e4dd216f8926d9a02aeb60d0edb74e68d1f510 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Wed, 2 Jun 2021 18:39:16 +0200 Subject: [PATCH] Adjust to upstream changes This will use a) the dependencies and b) the intersphinx links from upstream "create-docs-theme". --- docs/conf.py | 6 ---- docs/create-sharded-table.rst | 6 ++-- docs/create-user.rst | 12 ++++---- docs/first-use.rst | 10 +++---- docs/generate-time-series/cli.rst | 12 ++++---- docs/generate-time-series/go.rst | 14 +++++----- docs/generate-time-series/node.rst | 10 +++---- docs/generate-time-series/python.rst | 8 +++--- docs/index.rst | 2 +- docs/install.rst | 20 ++++++------- docs/normalize-intervals.rst | 42 ++++++++++++++-------------- docs/requirements.txt | 2 -- 12 files changed, 68 insertions(+), 76 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 8690800..e0341a6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,12 +10,6 @@ intersphinx_mapping.update({ - 'reference': ('https://crate.io/docs/crate/reference/', None), - 'crate-python': ('https://crate.io/docs/python/', None), - 'howtos': ('https://crate.io/docs/crate/howtos/', None), - 'admin-ui': ('https://crate.io/docs/crate/admin-ui/', None), - 'crash': ('https://crate.io/docs/crate/crash/', None), - 'clients-tools': ('https://crate.io/docs/crate/clients-tools/', None), 'matplotlib': ('https://matplotlib.org/stable/', None), 'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None), 'numpy': ('https://numpy.org/doc/stable/', None), diff --git a/docs/create-sharded-table.rst b/docs/create-sharded-table.rst index a34cbf2..5d2c119 100644 --- a/docs/create-sharded-table.rst +++ b/docs/create-sharded-table.rst @@ -5,11 +5,11 @@ Create sharded table ==================== One core concept CrateDB uses to distribute data across a cluster is -:ref:`sharding `. CrateDB splits every table into a +:ref:`sharding `. CrateDB splits every table into a configured number of shards, which are distributed evenly across the cluster. You can think of shards as a self-contained part of a table, that includes both a subset of records and corresponding indexing structures. If we -:ref:`create a table ` like the following: +:ref:`create a table ` like the following: .. code-block:: psql @@ -44,7 +44,7 @@ Partitioning ============ CrateDB also supports splitting up data across another dimension with -:ref:`partitioning `. You can think of a +:ref:`partitioning `. You can think of a partition as a set of shards. For each partition the number of shards defined by ``CLUSTERED INTO x SHARDS`` are created, when a first row with a specific ``partition key`` is inserted. diff --git a/docs/create-user.rst b/docs/create-user.rst index b723b69..3942c32 100644 --- a/docs/create-user.rst +++ b/docs/create-user.rst @@ -10,8 +10,8 @@ Introduction ------------ This part of the documentation sheds some light on the topics of -:ref:`reference:administration_user_management` and -:ref:`reference:administration-privileges`. +:ref:`crate-reference:administration_user_management` and +:ref:`crate-reference:administration-privileges`. CrateDB ships with a superuser account called "``crate``", which has the privileges to perform any action. However, with the default configuration, this @@ -20,13 +20,13 @@ installed on. If you are trying to connect from another machine, you are prompted to enter a username and password. In order to create a user that can be used to authenticate from a remote -machine, first :ref:`install crash ` or other +machine, first :ref:`install crash ` or other :ref:clients-tools:index` on the same machine you installed CrateDB on. Then, connect to CrateDB running on ``localhost``. While you can also perform the steps outlined below within -:ref:`admin-ui:index` itself, the walkthrough will outline how to do it -using the :ref:`crash:index` on the command line. +:ref:`crate-admin-ui:index` itself, the walkthrough will outline how to do it +using the :ref:`crate-crash:index` on the command line. ------- @@ -53,7 +53,7 @@ Grant all privileges to the newly created user: .. image:: _assets/img/create-user.png -Now try navigating to the :ref:`admin-ui:index` in your browser. In the URL +Now try navigating to the :ref:`crate-admin-ui:index` in your browser. In the URL below, please replace ``cratedb.example.org`` with the host name or IP address of the machine CreateDB is running on and sign in with your newly created user account:: diff --git a/docs/first-use.rst b/docs/first-use.rst index 344873e..a0214d2 100644 --- a/docs/first-use.rst +++ b/docs/first-use.rst @@ -19,7 +19,7 @@ Introducing the Admin UI ======================== CrateDB ships with a browser-based administration interface called -:ref:`Admin UI `. +:ref:`Admin UI `. The CrateDB Admin UI runs on every CrateDB node, and you can use it to inspect and interact with the whole CrateDB cluster in a number of ways. @@ -46,7 +46,7 @@ Introducing the CrateDB Shell The CrateDB Shell (aka Crash) is an interactive command-line interface (CLI) program for working with CrateDB on your favorite terminal. For further information about it, please follow up on its documentation at -:ref:`crash:index`. +:ref:`crate-crash:index`. .. NOTE:: @@ -75,7 +75,7 @@ Start building with CrateDB clients and tools ============================================= If you'd like to skip the tutorials and start building with CrateDB, you can -find a list of :ref:clients-tools:index` in a different section of the +find a list of :ref:`crate-clients-tools:index` in a different section of the documentation. @@ -84,5 +84,5 @@ documentation. Dive into CrateDB ================= -Check out the :ref:`howtos:index` for goal oriented topics. Alternatively, -check out the :ref:`reference:index` for a complete reference manual. +Check out the :ref:`crate-howtos:index` for goal oriented topics. Alternatively, +check out the :ref:`crate-reference:index` for a complete reference manual. diff --git a/docs/generate-time-series/cli.rst b/docs/generate-time-series/cli.rst index f529109..a565eaa 100644 --- a/docs/generate-time-series/cli.rst +++ b/docs/generate-time-series/cli.rst @@ -6,7 +6,7 @@ Generate time series data from the command line This tutorial will show you how to generate :ref:`mock time series data ` about the `International Space Station`_ (ISS) using the -:ref:`crash:index` and a little bit of `shell scripting`_. +:ref:`crate-crash:index` and a little bit of `shell scripting`_. .. SEEALSO:: @@ -23,7 +23,7 @@ Prerequisites CrateDB must be :ref:`installed and running `. -Crash is available as `pip`_ package. :ref:`Install ` it +Crash is available as `pip`_ package. :ref:`Install ` it like this: .. code-block:: console @@ -153,7 +153,7 @@ Start an interactive Crash session: Modify the argument if you wish to connect to a CrateDB node on a different host or port number. -Then, :ref:`create a table ` suitable for writing +Then, :ref:`create a table ` suitable for writing load averages. .. code-block:: psql @@ -165,7 +165,7 @@ load averages. CREATE OK, 1 row affected (0.726 sec) -In the :ref:`admin-ui:index`, you should see the new table when you navigate +In the :ref:`crate-admin-ui:index`, you should see the new table when you navigate to the *Tables* screen using the left-hand navigation menu: .. image:: ../_assets/img/generate-time-series/table.png @@ -181,7 +181,7 @@ statements directly from the command line. First, exit from the interactive Crash session (or open a new terminal). Then, use ``crash`` with the ``--command`` argument to execute an :ref:`INSERT -` query. +` query. .. code-block:: console @@ -199,7 +199,7 @@ use ``crash`` with the ``--command`` argument to execute an :ref:`INSERT Press the up arrow on your keyboard and hit *Enter* to run the same command a few more times. -When you're done, you can :ref:`select ` that data +When you're done, you can :ref:`select ` that data back out of CrateDB. .. code-block:: console diff --git a/docs/generate-time-series/go.rst b/docs/generate-time-series/go.rst index 22e3eb4..ff3dee5 100644 --- a/docs/generate-time-series/go.rst +++ b/docs/generate-time-series/go.rst @@ -135,7 +135,7 @@ keys which don't have a corresponding struct field are ignored. Now, create a function that makes an HTTP GET request to the Open Notify API endpoint and returns longitude and latitude as a -:ref:`reference:geo_point_data_type` declaration. +:ref:`crate-reference:geo_point_data_type` declaration. .. code-block:: go @@ -231,8 +231,8 @@ client: ) Then, in your main function, connect to CrateDB using the -:ref:`reference:postgres_wire_protocol` port (``5432``) and -:ref:`create a table ` suitable for writing ISS +:ref:`crate-reference:postgres_wire_protocol` port (``5432``) and +:ref:`create a table ` suitable for writing ISS position coordinates. .. code-block:: go @@ -265,7 +265,7 @@ Save your changes and run the code: When you run the script this time, the ``go`` command will look up the module containing the `pgx`_ package and add it to ``go.mod``. -In the :ref:`admin-ui:index`, you should see the new table when you navigate +In the :ref:`crate-admin-ui:index`, you should see the new table when you navigate to the *Tables* screen using the left-hand navigation menu: .. image:: ../_assets/img/generate-time-series/table.png @@ -277,7 +277,7 @@ Record the ISS position With the table in place, you can start recording the position of the ISS. Create some logic that calls your ``getISSPosition`` function and :ref:`insert -` the result into the ``iss`` table. +` the result into the ``iss`` table. .. code-block:: go @@ -309,7 +309,7 @@ Save your changes and run the code: Press the up arrow on your keyboard and hit *Enter* to run the same command a few more times. -When you're done, you can :ref:`select ` that data +When you're done, you can :ref:`select ` that data back out of CrateDB with this query: .. code-block:: psql @@ -399,7 +399,7 @@ Run the script from the command line: Sleeping for 10 seconds... As the script runs, you should see the table filling up in the -:ref:`admin-ui:index`. +:ref:`crate-admin-ui:index`. .. image:: ../_assets/img/generate-time-series/rows.png diff --git a/docs/generate-time-series/node.rst b/docs/generate-time-series/node.rst index 395661f..4d19685 100644 --- a/docs/generate-time-series/node.rst +++ b/docs/generate-time-series/node.rst @@ -118,7 +118,7 @@ First, import the `node-postgres`_ client: > const { Client } = require('pg') -Then `connect`_ to CrateDB, using the :ref:`reference:postgres_wire_protocol` port +Then `connect`_ to CrateDB, using the :ref:`crate-reference:postgres_wire_protocol` port (``5432``): .. code-block:: js @@ -129,7 +129,7 @@ Then `connect`_ to CrateDB, using the :ref:`reference:postgres_wire_protocol` po > await client.connect() -Finally, :ref:`create a table ` suitable for writing +Finally, :ref:`create a table ` suitable for writing ISS position coordinates. .. code-block:: js @@ -168,7 +168,7 @@ ISS position coordinates. Success! -In the :ref:`admin-ui:index`, you should see the new table when you navigate to +In the :ref:`crate-admin-ui:index`, you should see the new table when you navigate to the *Tables* screen using the left-hand navigation menu: .. image:: ../_assets/img/generate-time-series/table.png @@ -180,7 +180,7 @@ Record the ISS position With the table in place, you can start recording the position of the ISS. The following command calls your ``position`` function and will :ref:`insert -` the result into the ``iss`` table. +` the result into the ``iss`` table. .. code-block:: js @@ -212,7 +212,7 @@ The following command calls your ``position`` function and will :ref:`insert Press the up arrow on your keyboard and hit *Enter* to run the same command a few more times. -When you're done, you can :ref:`select ` that data +When you're done, you can :ref:`select ` that data back out of CrateDB. .. code-block:: js diff --git a/docs/generate-time-series/python.rst b/docs/generate-time-series/python.rst index 41f72ac..b190899 100644 --- a/docs/generate-time-series/python.rst +++ b/docs/generate-time-series/python.rst @@ -110,7 +110,7 @@ Get a :ref:`cursor `: >>> cursor = connection.cursor() -Finally, :ref:`create a table ` suitable for writing +Finally, :ref:`create a table ` suitable for writing ISS position coordinates. >>> cursor.execute( @@ -119,7 +119,7 @@ ISS position coordinates. ... position GEO_POINT)""" ... ) -In the :ref:`admin-ui:index`, you should see the new table when you navigate to +In the :ref:`crate-admin-ui:index`, you should see the new table when you navigate to the *Tables* screen using the left-hand navigation menu: .. image:: ../_assets/img/generate-time-series/table.png @@ -131,14 +131,14 @@ Record the ISS position With the table in place, you can start recording the position of the ISS. The following command calls your ``position`` function and will :ref:`insert -` the result into the ``iss`` table: +` the result into the ``iss`` table: >>> cursor.execute("INSERT INTO iss (position) VALUES (?)", [position()]) Press the up arrow on your keyboard and hit *Enter* to run the same command a few more times. -When you're done, you can :ref:`select ` that data +When you're done, you can :ref:`select ` that data back out of CrateDB. >>> cursor.execute('SELECT * FROM iss ORDER BY timestamp DESC') diff --git a/docs/index.rst b/docs/index.rst index e10f53b..61fa70c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,7 +22,7 @@ massive amounts of machine data in real-time. .. SEEALSO:: - Check out the :ref:`howtos:index` and the :ref:`reference:index`. + Check out the :ref:`crate-howtos:index` and the :ref:`crate-reference:index`. .. NOTE:: diff --git a/docs/install.rst b/docs/install.rst index 287c16d..a40bf54 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -27,7 +27,7 @@ release channels, you can also download release archives and run CrateDB manually using the :ref:`install-adhoc` method. When the installation is finished, the CrateDB service should be up and -running. Then, you can access the :ref:`Admin UI ` from your +running. Then, you can access the :ref:`Admin UI ` from your local machine by navigating to:: http://localhost:4200/ @@ -218,8 +218,8 @@ official `CrateDB Docker image`_, use:: .. TIP:: If this command aborts with an error, please consult the :ref:`Docker - troubleshooting guide `. You are also - welcome learn more about :ref:`howtos:resource_constraints` with respect + troubleshooting guide `. You are also + welcome learn more about :ref:`crate-howtos:resource_constraints` with respect to running CrateDB within containers. .. CAUTION:: @@ -231,7 +231,7 @@ official `CrateDB Docker image`_, use:: container, all data will be lost. When you are ready to start using CrateDB for data you care about, please - consult the :ref:`full guide to CrateDB and Docker ` + consult the :ref:`full guide to CrateDB and Docker ` in order to configure the Docker setup appropriately by using persistent disk volumes. @@ -275,7 +275,7 @@ install CrateDB. The walkthrough is suitable to install and run CrateDB on both .. SEEALSO:: - Consult the :ref:`reference:cli` documentation for further information + Consult the :ref:`crate-reference:cli` documentation for further information about the ``./bin/crate`` command. @@ -316,7 +316,7 @@ Environment variables --------------------- When using the package-based setup flavor for :ref:`install-deb` or -:ref:`install-rpm`, the CrateDB startup script uses :ref:`reference:conf-env` +:ref:`install-rpm`, the CrateDB startup script uses :ref:`crate-reference:conf-env` from the ``/etc/default/crate`` file. When using the :ref:`install-adhoc` setup, the environment variables will be set by ``bin/crate{.sh,.bat}``. @@ -350,11 +350,11 @@ After successfully installing the software, you might want to follow up with Also, you might enjoy to be guided into further information about how to quickly adjust the :ref:`configuration settings `, read more -details about the :ref:`reference:config` of CrateDB, the background about -:ref:`howtos:bootstrap-checks`, multi-node configuration within the section -about :ref:`howtos:clustering` and :ref:`howtos:going-into-production`. When +details about the :ref:`crate-reference:config` of CrateDB, the background about +:ref:`crate-howtos:bootstrap-checks`, multi-node configuration within the section +about :ref:`crate-howtos:clustering` and :ref:`crate-howtos:going-into-production`. When operating a CrateDB cluster in production, :ref:`performance tuning -` will also be of interest. +` will also be of interest. .. NOTE:: diff --git a/docs/normalize-intervals.rst b/docs/normalize-intervals.rst index 61c8258..58e840b 100644 --- a/docs/normalize-intervals.rst +++ b/docs/normalize-intervals.rst @@ -227,9 +227,9 @@ Here are a few ways to improve this result: * The ``timestamp`` column isn't human-readable. It would be easier to understand the results if this value was as a human-readable time. - * The ``position`` column is a :ref:`reference:geo_point_data_type`. This data + * The ``position`` column is a :ref:`crate-reference:geo_point_data_type`. This data type isn't easy to plot on a traditional graph. However, you can use the - :ref:`distance() ` function to calculate the + :ref:`distance() ` function to calculate the distance between two ``geo_point`` values. If you compare ``position`` to a fixed place, you can plot distance over time for a graph showing you how far away the ISS is from some location of interest. @@ -265,13 +265,13 @@ Specifically: (using ``{}`` as a placeholder) to calculate the ``distance()`` of the ISS ground point in kilometers. - * You can use :ref:`CURRENT_TIMESTAMP ` with an - interval :ref:`value expression ` + * You can use :ref:`CURRENT_TIMESTAMP ` with an + interval :ref:`value expression ` (``INTERVAL '1' DAY``) to calculate a timestamp that is 24 hours in the - past. You can then use a :ref:`WHERE clause ` + past. You can then use a :ref:`WHERE clause ` to filter out records with a ``timestamp`` older than one day. - An :ref:`ORDER BY clause ` sorts the results + An :ref:`ORDER BY clause ` sorts the results by ``timestamp``, oldest first. * You can use the ``parse_dates`` argument to specify which columns @@ -400,20 +400,20 @@ Resample the data Here's the basic approach to resampling data at a lower frequency: 1. Truncate the ``time`` column to a less precise value (using - :ref:`trunc_date() `). + :ref:`trunc_date() `). For example, truncate times to the nearest minute. - 2. Group rows by date (using :ref:`GROUP BY `). + 2. Group rows by date (using :ref:`GROUP BY `). If you have six data points per minute and you are rounding ``time`` to the nearest minute, ``GROUP BY time`` will group six rows into one. - 3. Calculate an :ref:`aggregate ` value across the + 3. Calculate an :ref:`aggregate ` value across the grouped rows. For example, if you have six rows with six distances, you can calculate the - average distance (using :ref:`reference:aggregation-avg`) and return a + average distance (using :ref:`crate-reference:aggregation-avg`) and return a single value. .. TIP:: @@ -448,7 +448,7 @@ above and resamples the raw data by the minute: .. NOTE:: - :ref:`COUNT(*) ` can be used for debug purposes. + :ref:`COUNT(*) ` can be used for debug purposes. The ``records`` column produced by this query will tell you how many source rows have been grouped by the query per result row. @@ -532,7 +532,7 @@ You can perform null interpolation like so: of a join. You should resample this data at the same frequency as your null data. - 3. Join both tables with a left :ref:`inner join ` on + 3. Join both tables with a left :ref:`inner join ` on ``time`` to pull across any non-null values from the right-hand table. The result is a row set that has one row per interval for a fixed period with @@ -540,7 +540,7 @@ null values filling in for missing data. .. SEEALSO:: - Read more about :ref:`how joins work `. + Read more about :ref:`how joins work `. .. _ni-brief-example: @@ -617,8 +617,8 @@ Generate continuous null data for the past 24 hours ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can generate continuous null data with the :ref:`generate_series() -` *table function*. A :ref:`table -function ` is a function that produces a set +` *table function*. A :ref:`table +function ` is a function that produces a set of rows. For example, this query generates null values for every minute in the past 24 @@ -682,7 +682,7 @@ Bring it all together ~~~~~~~~~~~~~~~~~~~~~ To combine the null data with your resampled data, you can write a new query -that performs a left :ref:`reference:inner-joins`, as per the previous +that performs a left :ref:`crate-reference:inner-joins`, as per the previous :ref:`introductions `. .. code-block:: python @@ -717,24 +717,24 @@ In the code above: .. rst-class:: open - * The :ref:`generate_series() ` + * The :ref:`generate_series() ` table function creates a row set called ``time`` that has one row per minute for the past 24 hours. * The ``iss`` table can be joined to the ``time`` series by truncating the ``iss.timestamp`` column to the minute for the :ref:`join condition - `. + `. - * Like before, a :ref:`GROUP BY ` clause can be + * Like before, a :ref:`GROUP BY ` clause can be used to collapse multiple rows per minute into a single row per minute. - Similarly, the :ref:`reference:aggregation-avg` function can be used to + Similarly, the :ref:`crate-reference:aggregation-avg` function can be used to compute an aggregate ``distance`` value across multiple rows. There is no need to check for null values here because the ``avg()`` function discards null values. * To calculate the number of ``records``, you must subtract one from - :ref:`COUNT(*) ` to account for guaranteed + :ref:`COUNT(*) ` to account for guaranteed presence of one null value per minute interval. Test the function: diff --git a/docs/requirements.txt b/docs/requirements.txt index 7c655a4..ced14fe 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1 @@ -sphinx==3.5.4 -docutils==0.16 crate-docs-theme