Restructure docs, stage 1 (#3054)

* Update and restructure the Releases section
* Remove irrelevant beta and rc release notes
* Remove doubled text on index page
* Add the Overview article, based on Mons Anderson's article on Habr
* Create the new How-to section
* Move 'Getting started/What's next' to the new How-to section
* Add SQL Beginners' Guide to How-to
* Add CRUD operations how-to guide
* Fix links
* Point to the Cartridge tutorial explicitly

Part of #2805
Resolves #2487
Resolves #1467

Co-authored-by: Pavel Semyonov <[email protected]>
Co-authored-by: Evgeniy Osintsev <[email protected]>
Co-authored-by: Kseniia Antonova <[email protected]>
Co-authored-by: Nick Volynkin <[email protected]>

Author: 5 people

.gitignore

@@ -74,6 +74,6 @@ locale/*
 
 # tntcxx submodule
 
-/doc/getting_started/getting_started_cxx.rst
-/doc/getting_started/_includes/
+/doc/how-to/getting_started_cxx.rst
+/doc/how-to/_includes
 /doc/book/connectors/cxx/

build_submodules.sh

@@ -98,12 +98,12 @@ cp -rfv "${cartridge_kubernetes_root}" "${cartridge_kubernetes_dest}"
 
 # Tarantool C++ connector
 tntcxx_root="${project_root}/modules/tntcxx"
-tntcxx_gs_dest="${project_root}/doc/getting_started"
+tntcxx_howto_dest="${project_root}/doc/how-to"
 tntcxx_api_dest="${project_root}/doc/book/connectors"
 
 # Copy Tarantool C++ connector docs to the right places
 mkdir -p "${tntcxx_api_dest}/cxx/"
-mkdir -p "${tntcxx_gs_dest}/_includes"
-cp -rfv "${tntcxx_root}/doc/tntcxx_getting_started.rst" "${tntcxx_gs_dest}/getting_started_cxx.rst"
-cp -rfv "${tntcxx_root}/examples/" "${tntcxx_gs_dest}/_includes/examples/"
+mkdir -p "${tntcxx_howto_dest}/_includes"
+cp -rfv "${tntcxx_root}/doc/tntcxx_getting_started.rst" "${tntcxx_howto_dest}/getting_started_cxx.rst"
+cp -rfv "${tntcxx_root}/examples/" "${tntcxx_howto_dest}/_includes/examples/"
 cp -rfv "${tntcxx_root}/doc/tntcxx_api.rst" "${tntcxx_api_dest}/cxx/"

conf.py

@@ -21,6 +21,7 @@
     'sphinx.ext.ifconfig',
     'sphinx.ext.intersphinx',
     'sphinx.ext.extlinks',
+    'sphinx_panels',
     'sphinxcontrib.plantuml',
     'ext.custom',
     'ext.LuaDomain',

doc/book/intro.rst

@@ -16,7 +16,7 @@ To get started, you can install and launch Tarantool using
 or the online Tarantool server at http://try.tarantool.org.
 Either way, as the first tryout, you can follow the introductory exercises
 from :ref:`Chapter 2 "Getting started" <getting_started>`.
-If you want more hands-on experience, proceed to :ref:`Tutorials <tutorials>`
+If you want more hands-on experience, proceed to :ref:`How-to guides <how-to>`
 after you are through with Chapter 2.
 
 :ref:`Chapter 3 "Database" <database-chapter>` is about using Tarantool

doc/getting_started/index.rst

@@ -37,4 +37,7 @@ to write in/migrate to Tarantool.
    connecting_to_cluster
    change_schema_dynamically
    writing_cluster_code
-   whats_next
+
+To continue exploring Tarantool and its ecosystem, you might want to check out
+Tarantool :doc:`tutorials and guides <../how-to/index>`.
+The :ref:`Cartridge beginner tutorial <getting_started_cartridge>` can also be found there.

doc/getting_started/whats_next.rst

@@ -0,0 +1,8 @@
+Developing applications with Tarantool
+======================================
+
+..  toctree::
+    :maxdepth: 1
+
+    lua_tutorials
+    c_tutorial

doc/tutorials/c_tutorial.rst renamed to doc/how-to/app/c_tutorial.rst

@@ -1,8 +1,7 @@
 .. _box_space_examples:
 
-===============================================================================
-Examples
-===============================================================================
+CRUD operation examples
+=======================
 
 -------------------------------------------------------------------------------
 Example: using box.space functions to read _space tuples

doc/how-to/app/index.rst

@@ -4,7 +4,7 @@
 Connecting from your favorite language
 ================================================================================
 
-In the :doc:`previous sections </getting_started/getting_started_db>`,
+In the :ref:`previous sections <getting_started_db>`,
 you have learned how to create a Tarantool database.
 Now let's see how to connect to the database from different programming
 languages, such as Python, PHP, Go, and C++, and

doc/tutorials/lua_tutorials.rst renamed to doc/how-to/app/lua_tutorials.rst

@@ -0,0 +1,25 @@
+:noindex:
+:fullwidth:
+
+..  _tutorials:
+..  _how-to:
+
+How-to guides
+=============
+
+This chapter contains practical examples as well as
+tutorials for those who would like to dig deeper into Tarantool usage.
+
+If you are new to Tarantool, please see our
+:ref:`Getting Started guides <getting_started>` first.
+
+..  toctree::
+    :maxdepth: 2
+
+    Basic Tarantool tutorial <getting_started_db>
+    getting_started_connectors
+    getting_started_cartridge
+    crud
+    app/index
+    sql/index
+    other/index

doc/reference/reference_lua/box_space/examples.rst renamed to doc/how-to/crud.rst

@@ -0,0 +1,7 @@
+More guides
+===========
+
+..  toctree::
+    :maxdepth: 1
+
+    libslave

doc/getting_started/getting_started_cartridge.rst renamed to doc/how-to/getting_started_cartridge.rst

@@ -0,0 +1,12 @@
+SQL guides
+==========
+
+This section contains hands-on SQL guides.
+You might also want to read the in-depth :ref:`SQL reference <reference_sql>`.
+
+..  toctree::
+    :maxdepth: 1
+    
+    sql_beginners_guide
+    sql_tutorial
+    improving_mysql

doc/getting_started/getting_started_connectors.rst renamed to doc/how-to/getting_started_connectors.rst

@@ -788,3 +788,5 @@ The rules state that it should be impossible to use a low-level language to bypa
 integrity as defined in the relational-level language.
 In Tarantool's case, this is not true, for example one can execute a request
 with Tarantool's NoSQL to violate a foreign-key constraint that was defined with Tarantool's SQL.
+
+To learn more about SQL in Tarantool, check the :ref:`reference <reference_sql>`.

doc/getting_started/getting_started_db.rst renamed to doc/how-to/getting_started_db.rst

@@ -9,28 +9,11 @@
                            Tarantool -- Documentation
 -------------------------------------------------------------------------------
 
-.. wp_section::
-    :class: documentation-main-page-header
-
-    .. container:: documentation-main-page-header-path
-
-        |nbsp|
-
 .. wp_section::
     :class: b-documentation-toc
 
     .. container:: documentation-main-page
 
-        .. container:: documentation-main-page-title
-
-            Tarantool documentation
-
-        .. container:: documentation-main-page-description
-
-            This manual embraces all aspects of using Tarantool: from introductory
-            information and exercises for beginners -- to advanced instructions and
-            detailed references for power users and contributors.
-
         .. container:: documentation-main-page-content
 
             .. ifconfig:: language == 'ru'
@@ -64,10 +47,12 @@
                         </a>
                     </div>
 
-            .. toctree::
+            ..  toctree::
                 :maxdepth: 1
 
+                overview
                 getting_started/index
+                how-to/index
                 book/box/data_model
                 CRUD operations <reference/reference_lua/box_space>
                 book/box/indexes
@@ -82,6 +67,5 @@
                 book/box/engines/index
                 book/connectors
                 reference/index
-                tutorials/index
                 contributing/index
                 release/index

doc/getting_started/getting_started_go.rst renamed to doc/how-to/getting_started_go.rst

@@ -0,0 +1,105 @@
+Overview
+========
+
+What is Tarantool?
+------------------
+
+Tarantool combines an in-memory DBMS and a Lua server in a single platform
+providing ACID-compliant storage. It comes in two :ref:`editions <overview-editions>`:
+Community and Enterprise.
+The :ref:`use cases <overview-use_cases>` for Tarantool vary from ultra-fast cache
+to product data marts and smart queue services.
+
+Here are some of Tarantool's key characteristics:
+
+*   **Easy handling of OLTP workloads**: processes hundreds of thousands RPS
+
+*   **Data integrity**: write-ahead log (WAL) and data snapshots 
+
+*   **Cooperative multitasking**: transactions are performed in lightweight coroutines with no interthread locking
+
+*    **Advanced indexing**: composite indexes, locale support, indexing by nested fields and arrays
+
+*   **Compute close to data**: Lua server and Just-In-Time compiler on board
+
+*   **Durable distributed storage**: multiple failover modes and RAFT-based synchronous replication available
+    
+
+Tarantool allows executing code alongside data, which helps increase the speed of operations.
+Developers can implement any business logic with Lua,
+and a single Tarantool instance can also receive SQL requests.
+
+Tarantool has a variety of compatible `modules <https://www.tarantool.io/en/download/rocks>`__ (Lua rocks).
+You can pick the ones that you need and install them manually.
+
+Tarantool runs on Linux (x86_64, aarch64), Mac OS X (x86_64, M1), and FreeBSD (x86_64).
+
+You can use Tarantool with a programming language you're familiar with.
+For this purpose, a number of :ref:`connectors <getting_started_connectors>` are provided.
+
+..  _overview-editions:
+
+Editions
+--------
+
+Tarantool comes in two editions: the open-source **Community Edition (CE)**
+and the commercial **Enterprise Edition (EE)**.
+
+**Tarantool CE** lets you develop applications and speed up a system in operation.
+It features :ref:`synchronous replication <repl_sync>`, affords easy :ref:`scalability <sharding>`,
+and includes tools to develop efficient :ref:`applications <app_server>`.
+The `Tarantool community <https://t.me/tarantool>`__ helps with any practical questions
+regarding the Community Edition.
+
+**Tarantool EE** `provides advanced tools <https://www.tarantool.io/en/compare/>`__ for
+administration, deployment, and security management, along with premium support services.
+This edition includes all the Community Edition features
+and is more predictable in terms of solution cost and maintenance.
+The Enterprise Edition is shipped as an SDK and includes a number of closed-source modules.
+See the `documentation for Tarantool EE <https://www.tarantool.io/en/enterprise_doc/>`__.
+
+..  _overview-use_cases:
+
+Use cases
+---------
+
+Fast first-class storage
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+*   Primary storage
+
+    -   No secondary storage required
+
+*   Tolerance to high write loads
+*   Support of relational approaches
+*   Composite secondary indexes
+
+    -   Data access, data slices
+
+*   Predictable request latency
+
+Advanced cache
+~~~~~~~~~~~~~~
+
+*   Write-behind caching
+*   Secondary index support
+*   Complex invalidation algorithm support
+
+Smart queue
+~~~~~~~~~~~
+
+*   Support of various identification techniques
+*   Advanced task lifecycle management
+
+    -   Task scheduling
+    -   Archiving of completed tasks
+
+Data-centric applications
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*   Arbitrary data flows from many sources
+*   Incoming data processing
+*   Storage
+*   Background cycle processing
+
+    -   Scheduling support

doc/getting_started/getting_started_php.rst renamed to doc/how-to/getting_started_php.rst

@@ -25,9 +25,6 @@ Below is a list of all ``box.space`` functions and members.
         *   - Name
             - Use
 
-        *  - :doc:`./box_space/examples`
-           - Some useful examples
-
         *  - :doc:`./box_schema/space_create`
            - Create a space
 
@@ -172,10 +169,11 @@ Below is a list of all ``box.space`` functions and members.
         *  - :doc:`./box_space/_session_settings`
            - (Metadata) List of settings affecting behavior of the current session
 
+To see examples, visit the :ref:`how-to guide on CRUD operations <box_space_examples>`.
+
 .. toctree::
     :hidden:
 
-    box_space/examples
     box_schema/space_create
     box_space/alter
     box_space/auto_increment

doc/getting_started/getting_started_python.rst renamed to doc/how-to/getting_started_python.rst

@@ -20,7 +20,7 @@ To install the module, execute the following command:
 ..  NOTE::
 
     The ``vshard`` module requires Tarantool of the version 1.10.1 or higher,
-    `Tarantool development package <https://www.tarantool.io/en/doc/latest/tutorials/c_tutorial/#c-stored-procedures>`_,
+    :ref:`Tarantool development package <f_c_tutorial-c_stored_procedures>`,
     ``git``, ``cmake`` and ``gcc`` packages installed.
 
 .. _vshard-config-cluster:

doc/getting_started/images/cluster_create_replica_set-border-5px.png renamed to doc/how-to/images/cluster_create_replica_set-border-5px.png

@@ -14,7 +14,6 @@ This reference covers all the SQL statements and clauses supported by Tarantool.
     :numbered: 0
 
     sql
-    sql_beginners_guide
     sql_user_guide
     sql_statements_and_clauses
     sql_plus_lua

doc/getting_started/images/cluster_dry_run-border-5px.png renamed to doc/how-to/images/cluster_dry_run-border-5px.png

@@ -50,8 +50,7 @@ rather than starting with a NoSQL DBMS and adding syntax to it.
 What Tarantool's SQL manual delivers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following five parts of this document are: |br|
-The :ref:`SQL Beginners' Guide <sql_beginners_guide>` explains the basics of relational database management and SQL in particular. |br|
+The following parts of this document are: |br|
 The :ref:`SQL User Guide <sql_user_guide>` explains "How to get Started" and explains the terms and the syntax elements that
 apply for all SQL statements. |br|
 The :ref:`SQL Statements and Clauses <sql_statements_and_clauses>` guide explains, for each SQL statement, the format and the rules
@@ -61,3 +60,5 @@ and using the same database objects in both SQL and Lua. |br|
 The :ref:`SQL Features <sql>` list shows how the product conforms with the mandatory features of the SQL standard.
 
 Users are expected to know what databases are, and experience with other SQL DBMSs would be an advantage.
+To learn about the basics  of relational database management and SQL in particular,
+check the :ref:`SQL Beginners' Guide <sql_beginners_guide>` in the :ref:`How-to guides <how-to>` section.

doc/getting_started/images/cluster_hello_http-border-5px.png renamed to doc/how-to/images/cluster_hello_http-border-5px.png

@@ -0,0 +1,20 @@
+
+1.10.x (LTS)
+======
+
+Tarantool 1.10 LTS series includes the following releases:
+
+..  toctree::
+    :maxdepth: 1
+
+    1.10.14
+    1.10.13
+    1.10.12
+    1.10.11
+    1.10.10
+    1.10.9
+    1.10.8
+    1.10.7
+    1.10.6
+    1.10.5
+    Tarantool 1.10.0–1.10.4 <1.10>