From f9d43ebfb40073808e66c3edeeb32dd697ef7a61 Mon Sep 17 00:00:00 2001 From: patiencedaur Date: Mon, 9 Aug 2021 11:54:19 +0300 Subject: [PATCH 1/8] Fix header formatting in contributing.rst --- doc/contributing/contributing.rst | 55 ++++++++++++++----------------- 1 file changed, 25 insertions(+), 30 deletions(-) diff --git a/doc/contributing/contributing.rst b/doc/contributing/contributing.rst index 58c3b2bd59..348c720abf 100644 --- a/doc/contributing/contributing.rst +++ b/doc/contributing/contributing.rst @@ -1,12 +1,10 @@ .. _contributing: -================================================================================ How to be involved in Tarantool -================================================================================ +=============================== --------------------------------------------------------------------------------- What is Tarantool? --------------------------------------------------------------------------------- +------------------ Tarantool is an open source database that can store everything in RAM. Use Tarantool as a cache with the ability to save data to disk. @@ -20,9 +18,8 @@ Get rid of stale entries, sync with other data sources, implement an HTTP servic Go to :ref:`Getting Started ` and try Tarantool. --------------------------------------------------------------------------------- How to get help? --------------------------------------------------------------------------------- +---------------- We have a `special Telegram chat `_ for contributors. @@ -38,9 +35,8 @@ Also we have a Join the chat and ask questions. --------------------------------------------------------------------------------- How to leave feedback, ideas or suggestions? --------------------------------------------------------------------------------- +-------------------------------------------- You can leave your feedback or share ideas in different ways: @@ -69,9 +65,8 @@ you can leave your comment on `tarantool.io `_. Fill out the form at the bottom of the site and leave your email. We read each request and respond to them usually within 2 days. --------------------------------------------------------------------------------- How to contribute? --------------------------------------------------------------------------------- +------------------ There are many ways to contribute to Tarantool: @@ -83,9 +78,9 @@ There are many ways to contribute to Tarantool: * Spread the word -- Share your accomplishments in social media using the ``#tarantool`` hashtags (or CC ``@tarantooldb`` in Twitter). --------------------------------------------------------------------------------- + Tarantool Ecosystem --------------------------------------------------------------------------------- +------------------- Tarantool has a large ecosystem of tools around the product itself. @@ -113,9 +108,9 @@ Please do not hesitate to tag the maintainer in your GitHub ticket. Read further about the contribution to each of the blocks. --------------------------------------------------------------------------------- + You have a problem in documentation. How to tell about it and how to fix it? --------------------------------------------------------------------------------- +---------------------------------------------------------------------------- There are several ways to improve the documentation: @@ -147,9 +142,9 @@ It will take you 5 minutes and will help the whole community. If for some reason you cannot fix it, create a ticket in this repository and report the error. Such errors are fixed quickly. --------------------------------------------------------------------------------- + How to contribute to modules --------------------------------------------------------------------------------- +---------------------------- Tarantool is a database with an embedded application server. You can write any code in C and Lua and pack it in distributable modules. @@ -175,9 +170,9 @@ users can get your module easily. If you want to add your module to our GitHub organization -- `text us here `_. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Want to contribute to an existing module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Tasks for contributors can be easily found in the issues section of any repository by the "good first issue" tag. These are tasks of an initial or intermediate @@ -198,17 +193,17 @@ If you see that the project does not have a maintainer or is inactive, you can become one yourself. See the section :ref:`How to become a maintainer `. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Want to create a new module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can also create any custom modules and share them with the community. `Look at the module template `_ and write your own. --------------------------------------------------------------------------------- + How to contribute to Tarantool Core --------------------------------------------------------------------------------- +----------------------------------- Tarantool is written mostly in C. Some parts are written in C++ and Lua. @@ -241,9 +236,9 @@ A patch can be offered in two ways: the features there. See details :ref:`here `. --------------------------------------------------------------------------------- + How to write a test --------------------------------------------------------------------------------- +------------------- The database is a product that is expected to be as reliable as possible. We at Tarantool have developed a dedicated test framework for developing @@ -272,9 +267,9 @@ of writing tests for a module. Read: writing tests in Tarantool, writing unit tests. ??? --------------------------------------------------------------------------------- + How to contribute to language connectors --------------------------------------------------------------------------------- +---------------------------------------- A connector is a library that provides an API for accessing Tarantool from a programming language. Tarantool uses its own binary protocol for access, @@ -304,9 +299,9 @@ MAINTAINERS file: there will be contacts of the repository maintainer. If there is no such file -- `text us here `_. We will help you figure it out. We usually answer within one day. --------------------------------------------------------------------------------- + How to contribute to tools --------------------------------------------------------------------------------- +-------------------------- The Tarantool ecosystem has tools that help in operation, deploy applications, or allow working with Kubernetes. @@ -332,9 +327,9 @@ there and submit a pull request. .. _how_to_become_a_maintainer: --------------------------------------------------------------------------------- + How to become a maintainer --------------------------------------------------------------------------------- +-------------------------- Maintainers are people who can merge PRs or commit to master. We expect maintainers to answer questions and tickets in time, and do code reviews. From 13b9a7367e3b9c30bff0dcc0e7ee51993df0dca6 Mon Sep 17 00:00:00 2001 From: patiencedaur Date: Wed, 11 Aug 2021 14:22:05 +0300 Subject: [PATCH 2/8] Proofread contributing.rst up to line 150 --- doc/contributing/contributing.rst | 123 +++++++++++++++--------------- 1 file changed, 61 insertions(+), 62 deletions(-) diff --git a/doc/contributing/contributing.rst b/doc/contributing/contributing.rst index 348c720abf..4f8f4df780 100644 --- a/doc/contributing/contributing.rst +++ b/doc/contributing/contributing.rst @@ -1,15 +1,15 @@ .. _contributing: -How to be involved in Tarantool -=============================== +How to get involved in Tarantool +================================ What is Tarantool? ------------------ Tarantool is an open source database that can store everything in RAM. Use Tarantool as a cache with the ability to save data to disk. -Tarantool serves up to a million requests per second, secondary index searches, -and SQL support. +Tarantool serves up to a million requests per second, +allows for secondary index searches, and has SQL support. In Tarantool, you can execute code alongside data. This allows for faster operations. @@ -26,128 +26,127 @@ for contributors. We speak Russian and English in the chat. This is the easiest way to get your questions answered. -Many people are afraid to ask questions because they think they are -"wasting the experts' time," but no one really thinks so. +Many people are afraid to ask questions because they believe they are +"wasting the experts' time," but we don't really think so. Contributors are important to us. -Also we have a +We also have a `Stack Overflow tag `_. Join the chat and ask questions. -How to leave feedback, ideas or suggestions? --------------------------------------------- +How to leave feedback, ideas, or suggestions? +--------------------------------------------- You can leave your feedback or share ideas in different ways: -* **The simplest way** is to write - `here `__. - All you need to do is fill in one product comment field and send it to us. - If you don't mind -- leave your email address. +* **The simplest way** is to fill + `the feedback form `__. + All you need to do is fill in one product comment field and click "Send." + You can optionally provide your email address. If you wish, we can involve you in the product development process. * **A more technical way** is to create a ticket on GitHub. If you have a suggestion for a new feature or information about a bug, - `follow the link `_ - and leave a ticket. + `create a new GitHub issue `_. The link leads to the ``tarantool/tarantool`` repository. - For any other projects on GitHub select "Issues" - "New issue". + To leave feedback for our other projects on GitHub, select "Issues" > "New issue." See `an example of a feature request `_. -You can chat with the team in the general product chat. -They are divided by language: +To talk to our team about a product, go to one of our chats: * `Russian-speaking `_ -* `English-speaking `_ +* `English-speaking `_. -If this communication channel is inconvenient for you or there is simply no Telegram, -you can leave your comment on `tarantool.io `_. +If Telegram is inconvenient for you or simply isn't working, +leave your comment on `tarantool.io `_. Fill out the form at the bottom of the site and leave your email. -We read each request and respond to them usually within 2 days. +We read every request and respond to them usually within 2 days. -How to contribute? ------------------- +How to contribute +----------------- There are many ways to contribute to Tarantool: -* Code -- Contribute to the code. +* Code: Contribute to the code. We have components written in C, Lua, Python, Go, and other languages. -* Write -- Improve documentation, write blog posts, create tutorials or solution pages. -* Q&A -- Share your acknowledgments at Stack Overflow with tag - `#tarantool `_. -* Spread the word -- Share your accomplishments in social media using the - ``#tarantool`` hashtags (or CC ``@tarantooldb`` in Twitter). +* Write: Improve documentation, write blog posts, create tutorials or solution pages. +* Q&A: Share your experience on Stack Overflow with the + `#tarantool `_ tag. +* Spread the word: Share your accomplishments on social media using the + ``#tarantool`` hashtag (or CC ``@tarantooldb`` on Twitter). Tarantool Ecosystem ------------------- -Tarantool has a large ecosystem of tools around the product itself. - -We divide the Tarantool ecosystem into 4 types: +Tarantool has a large ecosystem of tools. +We divide the ecosystem into four large blocks: * Tarantool itself. * Modules for Tarantool. They can be written in C and Lua. * Connectors for programming languages. -* Applied tools. See a selection including external tools in the - `"awesome Tarantool" list `_. +* Applied tools. See the curated + `Awesome Tarantool list `_, + which also includes external tools. -First-time tasks can be easily found in the issues section of any repository by -the "good first issue" tag. These are beginner to intermediate tasks that will +To start contributing, check the "good first issue" tag +in the issues section of any of our repositories. +These are beginner to intermediate tasks that will help you get comfortable with the tool. See the `list of tasks `_ for the ``tarantool/tarantool`` repository. -For each repository we have a queue for reviewing, -and reviewing your changes can be delayed. -We try to give the first answer within two days. +There is a review queue in each of our repositories, +so your changes may not be reviewed immediately. +We usually give the first answer within two days. Depending on the ticket and its complexity, the review time may take a week or more. Please do not hesitate to tag the maintainer in your GitHub ticket. -Read further about the contribution to each of the blocks. +Read on to learn about contributing to different ecosystem blocks. -You have a problem in documentation. How to tell about it and how to fix it? ----------------------------------------------------------------------------- +Documentation: How to report and fix problems +--------------------------------------------- There are several ways to improve the documentation: * **The easiest one** is to leave your comment on the web documentation page. - All you need to do is click on the red button in the bottom right corner + To use the built-in feedback form, just click the red button in the bottom right corner of the page and fill in the comment field. You can point out an error, provide feedback on the current article, or suggest changes. - We review each comment and take it to work. - This form is built into the documentation on the Tarantool website. -* **Advanced** -- All Tarantool documentation tasks are - `in the repository `_. - Here you can take any tasks and suggest your changes. - Our documentation is written in the `reStructuredText markup `_, + We review each comment and work with it. +* **Advanced**: All Tarantool documentation tasks can be found in the + `repository `_. + Go to any task and suggest your changes. + We write our documentation using + `reStructuredText markup `_, and we have a :doc:`writing style guide `. - After making the change, you need to build the documentation locally and - see how it was laid out. This is done automatically in Docker. - `Read more in the README of the tarantool/doc repository `_. + After you make the change, build the documentation locally and + see how it works. This can be done automatically in Docker. + To learn more, check the `README of the tarantool/doc repository `_. -Some projects have their documentation in the code repository. -For example, `Tarantool Cartridge `_. +Some projects, like `Tarantool Cartridge `_, +have their documentation in the code repository. This is done on purpose, so the developers themselves can update it faster. -Instructions for building such documentation sets are in the code repository. +You can find instructions for building such documentation in the code repository. -If you find that the documentation in the README of a module or, for example, +If you find that the documentation provided in the README of a module or a connector is incomplete or wrong, the best way to influence this is to fix it -yourself. Clone the repository, fix the bug, and suggest changes as a PR (pull request). -It will take you 5 minutes and will help the whole community. +yourself. Clone the repository, fix the bug, and suggest changes in a pull request. +It will take you five minutes but it will help the whole community. -If for some reason you cannot fix it, create a ticket in this repository -and report the error. Such errors are fixed quickly. +If you cannot fix it for any reason, create a ticket in the repository +and report the error. It will be fixed promptly. How to contribute to modules ---------------------------- Tarantool is a database with an embedded application server. -You can write any code in C and Lua and pack it in distributable modules. +This means you can write any code in C and Lua and pack it in distributable modules. Here are examples of official modules: From d5641d1de4ff6debc40b1807bce43fa7568e0074 Mon Sep 17 00:00:00 2001 From: patiencedaur Date: Wed, 11 Aug 2021 16:41:27 +0300 Subject: [PATCH 3/8] Proofread up to 250 --- doc/contributing/contributing.rst | 127 +++++++++++++++--------------- 1 file changed, 65 insertions(+), 62 deletions(-) diff --git a/doc/contributing/contributing.rst b/doc/contributing/contributing.rst index 4f8f4df780..a88c377571 100644 --- a/doc/contributing/contributing.rst +++ b/doc/contributing/contributing.rst @@ -146,57 +146,58 @@ How to contribute to modules ---------------------------- Tarantool is a database with an embedded application server. -This means you can write any code in C and Lua and pack it in distributable modules. +This means you can write any code in C or Lua and pack it in distributable modules. -Here are examples of official modules: +We have official and unofficial modules. +Here are some of our official modules: -* `HTTP server `_ -- HTTP server implementation +* `HTTP server `_: HTTP server implementation with middleware support. -* `queue `_ - Tarantool implementation of - a persistent message queue. -* `metrics `_ - ready-to-use solution for +* `queue `_: Tarantool implementation of + the persistent message queue. +* `metrics `_: Ready-to-use solution for collecting metrics. -* `cartridge `_ - framework for writing +* `cartridge `_: Framework for writing distributed applications. -Modules are distributed through our package manager, which is already -preinstalled with Tarantool. +Official modules are provided in our organization on GitHub. -We have official modules and unofficial ones. -The official ones are those that are in our organization on GitHub. -But we distribute unofficial ones via our package manager too so that other -users can get your module easily. -If you want to add your module to our GitHub organization -- -`text us here `_. +All modules are distributed through our package manager, which is +pre-installed with Tarantool. +That also applies to unofficial modules, which means that +other users can get your module easily. +If you want to add your module to our GitHub organization, +`send us a message on Telegram `_. -Want to contribute to an existing module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Tasks for contributors can be easily found in the issues section of any repository -by the "good first issue" tag. These are tasks of an initial or intermediate -level of difficulty that will help you get comfortable in the module of interest. +Contributing to an existing module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Look at the +Tasks for contributors can be found in the issues section of any repository +under the "good first issue" tag. These tasks are beginner or intermediate +in terms of difficulty level, so you can comfortably get used to the module of your interest. + +Check the `currently open tasks `_ for the HTTP Server module. -The style guide for the Lua code we are following is :ref:`here `. +Please see our :doc:`Lua style guide `. -You can contact the current maintainer through MAINTAINERS, which is located -in the root of the repository. If there is not such a file -- +You can find the contact of the current maintainer in the MAINTAINERS file, located +in the root of the repository. If there is no such file, please `let us know `_. -We will respond within one to two days. +We will respond within two days. If you see that the project does not have a maintainer or is inactive, you can -become one yourself. -See the section :ref:`How to become a maintainer `. +become its maintainer yourself. +See the :ref:`How to become a maintainer ` section. -Want to create a new module -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Creating a new module +~~~~~~~~~~~~~~~~~~~~~ -You can also create any custom modules and share them with the community. +You can also create custom modules and share them with the community. `Look at the module template `_ and write your own. @@ -205,54 +206,56 @@ How to contribute to Tarantool Core ----------------------------------- Tarantool is written mostly in C. -Some parts are written in C++ and Lua. -Review can take longer because we want it to be reliable. +Some parts are in C++ and Lua. +Your contributions to Tarantool Core +may take longer to review because we want the code to be reliable. To start: -* :ref:`learn how to build Tarantool ` -* read about Tarantool architecture and main modules - (`here `__ and - `here `__) +* :doc:`Learn how to build Tarantool `. +* Read about Tarantool architecture and main modules on the + `developer site `__ and on + `GitHub `__. -We have standards that we try to adhere to when developing in Tarantool. -These are the Style Guide and Contribution Guide :ref:`links `. -They tell you how to format your code, how to format your commits, and how to -write your test and make sure you don't break anything. +In Tarantool development, we strive to follow the standards laid out in +our :doc:`style and contribution guides `. +These documents explain how to format your code and commits as well as +how to write tests without breaking anything accidentally. -They will also help you make a patch that is easier to check, which will allow -you to quickly push changes to master. +The guidelines also help you create patches that are easy to check, which allows +quickly pushing changes to master. -Before your first commit, read -`this article `_! +Please read about +`our code review procedure `_ +before making your first commit. -A patch can be offered in two ways: +Here are two ways to suggest a patch: -* (preferred) Using a fork and pull mechanism on GitHub: make changes to your - copy of the repository and submit to us for review. - See details `here `__. -* Suggest a patch via the mailing list. Our developers are discussing most of - the features there. - See details :ref:`here `. +* (preferred) Using the fork and pull mechanism on GitHub: Make changes to your + copy of the repository and submit it to us for review. Check the + `GitHub documentation `__ + to learn how to do it. +* Suggest a patch via the mailing list. This is where our developers discuss most features. + Learn more in :ref:`the article on submitting patches `. -How to write a test -------------------- +How to write tests +------------------ -The database is a product that is expected to be as reliable as possible. -We at Tarantool have developed a dedicated test framework for developing -test scripts that test Tarantool itself. The framework is called ``test-run``. +A database is a product that is expected to be as reliable as possible. +We at Tarantool created ``test-run``, a dedicated test framework for developing +scripts that test Tarantool itself. -Writing your own test is not difficult. See test examples here: +Writing your own test is not difficult. Check out the following examples: * `C unit test `_ * `Lua unit test `_ -We also have a CI that automatically checks build and test coverage for new +We also have a CI workflow that automatically checks build and test coverage for new changes on all supported operating systems. -This happens after any commit to the repository. +The workflow is launched after every commit to the repository. -The QA team has many tasks for specialists who are involved in checking the +Our QA team has many tasks for specialists involved in checking the quality of the product and tools. They provide test coverage for products, help develop the test framework, and introduce and maintain new tools to test the stability of releases. @@ -319,12 +322,12 @@ These tools can be installed via standard package managers: ``ansible galaxy``, ``yum``, ``apt-get``, respectively. If you have a tool that might go well in our curated -`"awesome Tarantool" list `_ +`Awesome Tarantool list `_ you can read the `guide for contributors `_ there and submit a pull request. -.. _how_to_become_a_maintainer: +.. _contributing-how_to_become_a_maintainer: How to become a maintainer From 35e9dbe2704832ffdd5f4cdbba053e35226d59e4 Mon Sep 17 00:00:00 2001 From: patiencedaur Date: Thu, 12 Aug 2021 13:03:17 +0300 Subject: [PATCH 4/8] Proofread contributing, examples, infra, and index --- doc/contributing/contributing.rst | 86 +++++++++++++++--------------- doc/contributing/docs/examples.rst | 37 ++++++------- doc/contributing/docs/infra.rst | 72 +++++++++++++------------ doc/contributing/index.rst | 3 +- 4 files changed, 98 insertions(+), 100 deletions(-) diff --git a/doc/contributing/contributing.rst b/doc/contributing/contributing.rst index a88c377571..c0477a6ed4 100644 --- a/doc/contributing/contributing.rst +++ b/doc/contributing/contributing.rst @@ -77,7 +77,7 @@ There are many ways to contribute to Tarantool: ``#tarantool`` hashtag (or CC ``@tarantooldb`` on Twitter). -Tarantool Ecosystem +Tarantool ecosystem ------------------- Tarantool has a large ecosystem of tools. @@ -249,108 +249,108 @@ scripts that test Tarantool itself. Writing your own test is not difficult. Check out the following examples: * `C unit test `_ -* `Lua unit test `_ +* `Lua unit test `_. We also have a CI workflow that automatically checks build and test coverage for new changes on all supported operating systems. The workflow is launched after every commit to the repository. -Our QA team has many tasks for specialists involved in checking the -quality of the product and tools. They provide test coverage for products, -help develop the test framework, and introduce and maintain new tools to test -the stability of releases. +We have many tasks for QA specialists. Our QA team provides test coverage for our products, +helps develop the test framework, and introduces and maintains new tools to test +the stability of our releases. -We test modules differently: for modules, we use the -`luatest `_ framework. -This is a fork of the popular framework in the Lua community, which we have +For modules, we use `luatest `_--- +our fork of a framework popular in the Lua community, enhanced and optimized for our tasks. See `examples `_. of writing tests for a module. -Read: writing tests in Tarantool, writing unit tests. ??? +.. // Read: writing tests in Tarantool, writing unit tests. ??? How to contribute to language connectors ---------------------------------------- -A connector is a library that provides an API for accessing Tarantool from +A connector is a library that provides an API to access Tarantool from a programming language. Tarantool uses its own binary protocol for access, and the connector's task is to transfer user requests to the database and application server in the required format. Data access connectors have already been implemented for all major languages. -If you want to write your own connector, you first need to familiarize yourself with the Tarantool binary protocol. Its current description can be found :ref:`here `. +If you want to write your own connector, +you first need to familiarize yourself with the Tarantool binary protocol. +Read :doc:`the protocol description ` to learn more. We consider the following connectors as references: * https://github.com/tarantool-php/client -* `net.box `_ — binary protocol client in Tarantool +* `net.box `_---Tarantool + binary protocol client You can look at them to understand how to do it right. -The Tarantool ecosystem has connectors that are supported by the Tarantool team -itself, and there are connectors that are developed and supported exclusively by the -community. All of them have their pros and cons. See a +Some connectors in the Tarantool ecosystem are supported by the Tarantool team. +Others are developed and supported exclusively by the community. +All of them have their pros and cons. See the `complete list of connectors and their recommended versions `_. -If you are using an existing connector from the community and want to implement -new features or fix a bug, then send your PRs via GitHub to the desired repository. +If you are using a community connector and want to implement +new features for it or fix a bug, send your PRs via GitHub to the connector repository. -To contact the author of the connector in case of questions, look in the -MAINTAINERS file: there will be contacts of the repository maintainer. -If there is no such file -- `text us here `_. +If you have questions for the author of the connector, check the +MAINTAINERS file for the repository maintainer's contact. +If there is no such file, `send us a message on Telegram `_. We will help you figure it out. We usually answer within one day. How to contribute to tools -------------------------- -The Tarantool ecosystem has tools that help in operation, deploy applications, -or allow working with Kubernetes. +The Tarantool ecosystem has tools that facilitate the workflow, +help with application deployment, or allow working with Kubernetes. -Examples of tools from the Tarantool team: +Here are some of the tools created by the Tarantool team: * `ansible-cartridge `_: - Ansible role for deploying an application on Cartridge + An Ansible role to deploy Cartridge applications. * `cartridge-cli `_: - CLI utility for creating applications, launching clusters locally on Cartridge - and solving operational problems + A CLI utility for creating applications, launching clusters locally on Cartridge, + and solving operation problems. * `tarantool-operator `_: - Kubernetes operator for cluster orchestration + A Kubernetes operator for cluster orchestration. These tools can be installed via standard package managers: -``ansible galaxy``, ``yum``, ``apt-get``, respectively. +``ansible galaxy``, ``yum``, or ``apt-get``. If you have a tool that might go well in our curated -`Awesome Tarantool list `_ -you can read the +`Awesome Tarantool list `_, +read the `guide for contributors `_ -there and submit a pull request. +and submit a pull request. .. _contributing-how_to_become_a_maintainer: - How to become a maintainer -------------------------- Maintainers are people who can merge PRs or commit to master. -We expect maintainers to answer questions and tickets in time, and do code reviews. +We expect maintainers to answer questions and tickets on time as well as do code reviews. -If you need to get a review but no one responds for a week, take a look at the -Maintainers section of the ``README.md`` in the repository. +If you need to get a review but no one responds within a week, take a look at the +Maintainers section of the repository's ``README.md``. Write to the person listed there. -If you have not received an answer in 3-4 days, you can escalate the question -`here `__. +If you have not received an answer within 3--4 days, you can escalate the question +`on Telegram `__. -A repository may have no maintainers (the Maintainers list in ``README.md`` is empty), -or existing maintainers may be inactive. Then you can become a maintainer yourself. +A repository may have no maintainers (empty Maintainers list in ``README.md``), +or the existing maintainers may be inactive. In this case, you can become a maintainer yourself. We think it's better if the repository is maintained by a newbie than if the -repository is dead. So don't be shy: we love maintainers and help them figure it out. +repository is dead. So don't be shy: we love maintainers and help them figure it all out. All you need to do is fill out `this form `_. -Indicate which repository you want to access, +Tell us what repository you want to access, the reason (inactivity, the maintainer is not responding), and how to contact you. -We will consider the application in 1 day and either give you the rights +We will consider your application in 1 day and either give you the rights or tell you what else needs to be done. diff --git a/doc/contributing/docs/examples.rst b/doc/contributing/docs/examples.rst index cba83331f0..f059ce52d1 100644 --- a/doc/contributing/docs/examples.rst +++ b/doc/contributing/docs/examples.rst @@ -1,10 +1,8 @@ - -================================================================================ Examples and templates -================================================================================ +====================== -In this document, we explain general guidelines for describing Tarantool API and -give some examples and templates. +This document contains general guidelines for describing the Tarantool API, +as well as examples and templates. Use this checklist for documenting a function or a method: @@ -14,39 +12,38 @@ Use this checklist for documenting a function or a method: * Return type (if exists) * Possible errors (if exist) * Complexity factors (if exist) -* Note re storage engine (if exists) +.. // * Note re storage engine (if exists) * Example(s) * Extra information (if needed) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Documenting a function -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Documenting functions +~~~~~~~~~~~~~~~~~~~~~ -We describe functions of Tarantool modules via Sphinx directives ``.. module::`` -and ``.. function::``: +We use the Sphinx directives ``.. module::`` +and ``.. function::`` to describe functions of Tarantool modules: .. literalinclude:: ./_includes/function_template.rst :language: rst -And the resulting output looks like this: +The resulting output looks like this: .. include:: ./_includes/function_template.rst -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Documenting class method and data -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Documenting class methods and data +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Description of a method is similar to a function, but the ``.. class::`` +Methods are described similarly to functions, but the ``.. class::`` directive, unlike ``.. module::``, requires nesting. -As for documenting data, it will be enough to write a description, -a return type, and an example. +As for data, it's enough to write the description, the return type, and an example. -Here is an example of documenting a method and data of a class ``index_object``: +Here is the example documentation describing +the method and data of the ``index_object`` class: .. literalinclude:: ./_includes/class_template.rst :language: rst And the resulting output looks like this: -.. include:: ./_includes/class_template.rst \ No newline at end of file +.. include:: ./_includes/class_template.rst + \ No newline at end of file diff --git a/doc/contributing/docs/infra.rst b/doc/contributing/docs/infra.rst index f254be58b0..80a6b960fb 100644 --- a/doc/contributing/docs/infra.rst +++ b/doc/contributing/docs/infra.rst @@ -2,8 +2,8 @@ Documentation infrastructure ============================= -In this section of the :doc:`documentation guidelines `, -we deal with some support activities to ensure the correct building of +This section of the :doc:`documentation guidelines ` +discusses some of the support activities that ensure the correct building of documentation. .. _guidelines_doc_submodules: @@ -11,20 +11,23 @@ documentation. Adding submodules ----------------- -The source files with the documentation content are mainly stored in the +The documentation source files are mainly stored in the `documentation repository `_. -However, in some of the cases the content source files are stored in -repositories of other Tarantool-related products and modules, for example, -`Cartridge `_, +However, in some cases, they are stored in the +repositories of other Tarantool-related products +or modules---`Cartridge `_, `Monitoring `__, -and some others. +and others. -In this case, we need to add such a repository containing the source files -as a submodule to the `documentation repository `_ -and set up other necessary settings to ensure the proper building of the entire -body of Tarantool documentation presented at the `official web-site `_. +If you are working with source files from a product or module repository, +add that repository as a submodule to the +`documentation repository `_ +and configure other necessary settings to ensure that the entire +body of Tarantool documentation, +presented on the `official website `_, +is built properly. -The steps to do that are the following: +Here is how to do that: .. contents:: :local: @@ -35,7 +38,7 @@ The steps to do that are the following: 1. Add a submodule ~~~~~~~~~~~~~~~~~~ -First, we need to add a repository containing the content source files as +First, we need to add the repository with content source files as a submodule. #. Make sure you are in the root directory of the documentation repository. @@ -49,7 +52,7 @@ a submodule. cd .. -#. Check that the new submodule appears in the ``.gitmodules`` file, for example: +#. Check that the new submodule is in the ``.gitmodules`` file, for example: .. code-block:: ini @@ -62,30 +65,30 @@ a submodule. 2. Update build_submodules.sh ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Next, we should define what directories and files are to be copied from -the submodule repository into the documentation one before building +Now define what directories and files are to be copied from +the submodule repository to the documentation repository before building documentation. These settings are defined in the ``build_submodules.sh`` file -which is in the root directory of the documentation repository. +in the root directory of the documentation repository. -We can take examples of the already existing submodules to show the logic of -the settings. +Here are some real submodule examples +that show the logic of the settings. metrics ^^^^^^^ -In case of the ``metrics`` submodule, the content source files are in the +The content source files for the ``metrics`` submodule are in the ``./doc/monitoring`` directory of the submodule repository. In the final documentation view, the content should appear in the `Monitoring `__ chapter (``https://www.tarantool.io/en/doc/latest/book/monitoring/``). -So, we need to: +To make this work: -* create a directory at ``./doc/book/monitoring/``. -* copy the entire content of the ``./modules/metrics/doc/monitoring/`` directory to +* Create a directory at ``./doc/book/monitoring/``. +* Copy the entire content of the ``./modules/metrics/doc/monitoring/`` directory to ``./doc/book/monitoring/``. -The corresponding lines in the ``build_submodules.sh`` file are the following: +Here are the corresponding lines in ``build_submodules.sh``: .. code-block:: bash @@ -95,25 +98,25 @@ The corresponding lines in the ``build_submodules.sh`` file are the following: mkdir -p "${monitoring_dest}" yes | cp -rf "${monitoring_root}" "${monitoring_dest}/" -The ``${project_root}`` variable is defined earlier as ``project_root=$(pwd)``. -We should start the documentation build from the documentation repository root -directory so that will be the value of the variable. +The ``${project_root}`` variable is defined earlier in the file as ``project_root=$(pwd)``. +This is because the documentation build has to start from the documentation repository root +directory. cartridge_cli ^^^^^^^^^^^^^ -In case of the ``cartridge_cli`` submodule, the content source is in -the ``README.rst`` file located in the directory of the submodule repository. +The content source file for the ``cartridge_cli`` submodule is +``README.rst``, located in the directory of the submodule repository. In the final documentation view, the content should appear here: ``https://www.tarantool.io/en/doc/latest/book/cartridge/cartridge_cli/``. -So, we need to: +To make this work: -* create a directory at ``./doc/book/cartridge/cartridge_cli`` -* copy ``./modules/cartridge_cli/README.rst`` to +* Create a directory at ``./doc/book/cartridge/cartridge_cli``. +* Copy ``./modules/cartridge_cli/README.rst`` to ``./doc/book/cartridge/cartridge_cli/index.rst``. -The corresponding settings in the ``build_submodules.st`` file are the following: +Here ar the corresponding settings in ``build_submodules.sh``: .. code-block:: bash @@ -130,5 +133,4 @@ The corresponding settings in the ``build_submodules.st`` file are the following 3. Update .gitignore ~~~~~~~~~~~~~~~~~~~~ -Finaly, we should add paths to the copied directories and files to -the ``.gitignore`` file. +Finally, add paths to the copied directories and files to ``.gitignore``. diff --git a/doc/contributing/index.rst b/doc/contributing/index.rst index 2889474e4f..50a0ae774e 100644 --- a/doc/contributing/index.rst +++ b/doc/contributing/index.rst @@ -1,8 +1,7 @@ .. _contributing-reference: -******************************************************************************** Contributing -******************************************************************************** +************ .. toctree:: :maxdepth: 2 From 16d45c0f104f87333579649d450294c7b644e0eb Mon Sep 17 00:00:00 2001 From: patiencedaur Date: Thu, 12 Aug 2021 14:23:34 +0300 Subject: [PATCH 5/8] More proofreading --- doc/contributing/contributing.rst | 12 ++--- doc/contributing/docs/examples.rst | 3 +- doc/contributing/docs/infra.rst | 3 +- doc/contributing/docs/markup.rst | 11 ++--- doc/contributing/docs/sphinx-warnings.rst | 59 ++++++++++++----------- 5 files changed, 44 insertions(+), 44 deletions(-) diff --git a/doc/contributing/contributing.rst b/doc/contributing/contributing.rst index c0477a6ed4..af113b9f09 100644 --- a/doc/contributing/contributing.rst +++ b/doc/contributing/contributing.rst @@ -56,10 +56,10 @@ See `an example of a feature request `_ -* `English-speaking `_. +* `English-speaking `_ If Telegram is inconvenient for you or simply isn't working, -leave your comment on `tarantool.io `_. +you can leave your comment on `tarantool.io `_. Fill out the form at the bottom of the site and leave your email. We read every request and respond to them usually within 2 days. @@ -249,7 +249,7 @@ scripts that test Tarantool itself. Writing your own test is not difficult. Check out the following examples: * `C unit test `_ -* `Lua unit test `_. +* `Lua unit test `_ We also have a CI workflow that automatically checks build and test coverage for new changes on all supported operating systems. @@ -312,12 +312,12 @@ help with application deployment, or allow working with Kubernetes. Here are some of the tools created by the Tarantool team: * `ansible-cartridge `_: - An Ansible role to deploy Cartridge applications. + an Ansible role to deploy Cartridge applications. * `cartridge-cli `_: - A CLI utility for creating applications, launching clusters locally on Cartridge, + a CLI utility for creating applications, launching clusters locally on Cartridge, and solving operation problems. * `tarantool-operator `_: - A Kubernetes operator for cluster orchestration. + a Kubernetes operator for cluster orchestration. These tools can be installed via standard package managers: ``ansible galaxy``, ``yum``, or ``apt-get``. diff --git a/doc/contributing/docs/examples.rst b/doc/contributing/docs/examples.rst index f059ce52d1..73c0eada1a 100644 --- a/doc/contributing/docs/examples.rst +++ b/doc/contributing/docs/examples.rst @@ -12,9 +12,9 @@ Use this checklist for documenting a function or a method: * Return type (if exists) * Possible errors (if exist) * Complexity factors (if exist) -.. // * Note re storage engine (if exists) * Example(s) * Extra information (if needed) +.. // * Note re storage engine (if exists). TODO (was the third from last bullet point) Documenting functions ~~~~~~~~~~~~~~~~~~~~~ @@ -46,4 +46,3 @@ the method and data of the ``index_object`` class: And the resulting output looks like this: .. include:: ./_includes/class_template.rst - \ No newline at end of file diff --git a/doc/contributing/docs/infra.rst b/doc/contributing/docs/infra.rst index 80a6b960fb..8d407d681b 100644 --- a/doc/contributing/docs/infra.rst +++ b/doc/contributing/docs/infra.rst @@ -22,7 +22,8 @@ and others. If you are working with source files from a product or module repository, add that repository as a submodule to the `documentation repository `_ -and configure other necessary settings to ensure that the entire +and configure other necessary settings. +This will ensure that the entire body of Tarantool documentation, presented on the `official website `_, is built properly. diff --git a/doc/contributing/docs/markup.rst b/doc/contributing/docs/markup.rst index e46db284f3..a9d4be401b 100644 --- a/doc/contributing/docs/markup.rst +++ b/doc/contributing/docs/markup.rst @@ -1,12 +1,11 @@ -================================================================================ + Markup reference -================================================================================ +================ -Tarantool documentation is built via +Tarantool documentation is built via the `Sphinx `_ engine and is written in -`reStructuredText `_ -markup. -This section will guide you through our typical cases while writing the docs. +`reStructuredText `_. +This section will guide you through our typical documentation formatting cases. .. toctree:: diff --git a/doc/contributing/docs/sphinx-warnings.rst b/doc/contributing/docs/sphinx-warnings.rst index de3b5e1293..a72c4b6534 100644 --- a/doc/contributing/docs/sphinx-warnings.rst +++ b/doc/contributing/docs/sphinx-warnings.rst @@ -1,10 +1,10 @@ Sphinx-build warnings reference =============================== -This document will guide you through the possible warnings raised by Sphinx engine +This document will guide you through the warnings that can be raised by Sphinx while building the docs. -Below we cite a list with the most frequent warnings and the ways of solutions. +Below are the most frequent warnings and the ways to solve them. Bullet list ends without a blank line; unexpected unindent ---------------------------------------------------------- @@ -50,8 +50,8 @@ for the right spelling. // some code here -Sometimes, however, there's no appropriate lexer, or the code snippet can't be -lexed properly. In such case, use ``code-block:: text``. +However, sometimes there's no appropriate lexer or the code snippet can't be +lexed properly. In that case, use ``code-block:: text``. Duplicate explicit target name: "..." ------------------------------------- @@ -61,21 +61,21 @@ Duplicate explicit target name: "..." .. code-block:: rst * `Install `_ - ``git``, a version control system. + ``git``, the version control system. * `Install `_ the ``unzip`` utility. **Solution:** -Sphinx-builder raises warnings when we call different targets the same names. +Sphinx-builder raises warnings when we call different targets the same name. Sphinx developers `recommend `_ using double underlines ``__`` in such cases to avoid this. .. code-block:: rst * `Install `__ - ``git``, a version control system. + ``git``, the version control system. * `Install `__ the ``unzip`` utility. @@ -87,30 +87,31 @@ This warning means that you forgot to put the document name in the toctree. **Solution:** -If you don't need it there, place ``:orphan:`` directive at the top of the file. -Or, if this file is included somewhere or reused, add it to the _includes directory. -These directories are ignored by Sphinx because we put them in ``exclude_patterns`` -in ``conf.py`` file. +If you don't want to include the document in a toctree, +place the ``:orphan:`` directive at the top of the file. +If this file is already included somewhere or reused, add it to the _includes directory. +Sphinx ignores everything in this directory +because we list it among ``exclude_patterns`` in ``conf.py``. Duplicate label "...", other instance in ".../.../..." ------------------------------------------------------ -**Example:** +.. // **Example:** -This happens if you include the contents of one file with tags in another. -Then Sphinx thinks the tags are repeated. +This happens if you include the contents of a file into another file, +when the included file has tags in it. +In this, Sphinx thinks the tags are repeated. **Solution:** -As in previous case, don't forget to add such file in _includes or avoid using -tags within it. +As in the previous case, add the file to _includes or avoid using tags in it. Malformed hyperlink target -------------------------- **Similar warning:** Unknown target name: "..." -Check the spelling of the target or the accuracy of the tag. +Check the target spelling and the tag syntax. **Example:** @@ -124,7 +125,7 @@ Check the spelling of the target or the accuracy of the tag. **Solution:** -Semicolon is missing in tag definition: +A semicolon is missing in the tag definition: .. code-block:: rst @@ -135,13 +136,13 @@ Toctree contains reference to nonexisting document '...' **Example:** -This may happen when you, for example, refer to the wrong path to a document. +This may happen when you refer to a wrong path to a document. **Solution:** Check the path. -If the path is in ``cartridge`` or another submodule, check that you've +If the path points to ``cartridge`` or another submodule, check that you've :doc:`built the submodules content ` before building docs. @@ -164,25 +165,25 @@ We recommend using custom captions with ``:ref:``: **See also:** -* :doc:`/contributing/docs/markup/links` +* :doc:`Links and references ` Unexpected indentation ---------------------- The reStructuredText syntax is based on indentation, much like in Python. -In a block of content, all lines should be equally indented. -An increase or decrease in indentation means the end of the current block and +All lines in a block of content must be equally indented. +An increase or decrease in indentation denotes the end of the current block and the beginning of a new one. **Example:** -Note: dots show indentation spaces in these examples. -For example, ``|..|`` means a two-space indentation. +Note: In the following examples, dots stand for indentation spaces. +For example, ``|..|`` denotes a two-space indentation. .. code-block:: rst |..|* (Engines) Improve dump start/stop logging. When initiating memory dump, print - how much memory is going to be dumped, expected dump rate, ETA, and the recent + how much memory is going to be dumped, the expected dump rate, ETA, and the recent write rate. **Solution:** @@ -190,12 +191,12 @@ For example, ``|..|`` means a two-space indentation. .. code-block:: rst *|...|(Engines) Improve dump start/stop logging. When initiating memory dump, print - |....|how much memory is going to be dumped, expected dump rate, ETA, and the recent + |....|how much memory is going to be dumped, the expected dump rate, ETA, and the recent |....|write rate. **See also:** -* :doc:`/contributing/docs/markup/intro` +* :doc:`General syntax guidelines ` Unknown document ---------------- @@ -208,7 +209,7 @@ Unknown document **Solution:** -Sphinx did not recognise the file path correctly +Sphinx did not recognize the file path correctly due to a missing slash at the beginning, so let's just put it there: .. code-block:: rst From 45a772e42bedeeed74f2b4e2eb0fc1d943933280 Mon Sep 17 00:00:00 2001 From: patiencedaur Date: Thu, 12 Aug 2021 14:36:24 +0300 Subject: [PATCH 6/8] Proofread style.rst --- doc/contributing/docs/style.rst | 48 +++++++++++++++++---------------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/doc/contributing/docs/style.rst b/doc/contributing/docs/style.rst index 8ce42ef88b..fe33d0fb89 100644 --- a/doc/contributing/docs/style.rst +++ b/doc/contributing/docs/style.rst @@ -5,20 +5,20 @@ Language and style US vs British spelling ---------------------- -We use English US spelling. +We use the US English spelling. Instance vs server ------------------ -We say "instance" rather than "server" to refer to an instance of Tarantool -server. This keeps the manual terminology consistent with names like +We say "instance" rather than "server" to refer to a Tarantool +server instance. This keeps the manual terminology consistent with names like ``/etc/tarantool/instances.enabled`` in the Tarantool environment. -Wrong usage: "Replication allows multiple Tarantool *servers* to work on copies -of the same databases." +Wrong usage: "Replication allows multiple Tarantool *servers* to work with copies +of the same database." -Correct usage: "Replication allows multiple Tarantool *instances* to work on -copies of the same databases." +Correct usage: "Replication allows multiple Tarantool *instances* to work with +copies of the same database." Express one idea in a sentence ------------------------------ @@ -51,32 +51,33 @@ Simple sentences are easier to read, understand and translate. - memtx is an in-memory storage engine. It is the default and was the first to arrive. - * - A replica set from which the bucket is being migrated is called a source; - a target replica set to which the bucket is being migrated is called a destination. - - A replica set from which the bucket is being migrated is called a source. - A target replica set to which the bucket is being migrated is called a destination. + * - The replica set from where the bucket is being migrated is called the source; + the target replica set where the bucket is being migrated to is called the destination. + - The replica set from where the bucket is being migrated is called the source. + The target replica set where the bucket is being migrated to is called the destination. Don't use i.e. and e.g. ----------------------- Don't use the following contractions: -* `"i.e." `_ - —from Latin "id est". Use "that is" or "which means" instead. -* `"e.g." `_ - —from Latin "exempli gratia". Use "for example" or "such as" instead. +* `"i.e." `_---from + the Latin "id est". Use "that is" or "which means" instead. +* `"e.g." `_---from + the Latin "exempli gratia". Use "for example" or "such as" instead. Many people, especially non-native English speakers, -aren't familiar or don't know the difference between +aren't familiar with the `"i.e." and "e.g." contractions -`_. -So it's best to avoid using them. +`_ +or don't know the difference between them. +For this reason, it's best to avoid using them. -Specify a link text -------------------- +Specify link text +----------------- -While giving a :doc:`link `, specify clearly -where this link leads. Thus, you will not mislead a reader. +When you provide a :doc:`link `, clearly specify +where it leads. In this way, you will not mislead the reader. Bad example: @@ -89,4 +90,5 @@ Good example: For more details, refer to the documentation on :doc:`making links `. - Use full :doc:`link names `. \ No newline at end of file + Use full :doc:`link names `. + \ No newline at end of file From 63ca589efcc200fe675f8cfd8bfa4a1a025bdf86 Mon Sep 17 00:00:00 2001 From: patiencedaur Date: Thu, 12 Aug 2021 18:01:44 +0300 Subject: [PATCH 7/8] Prrofread terms.rst --- doc/contributing/docs/terms.rst | 63 +++++++++++++++++---------------- 1 file changed, 32 insertions(+), 31 deletions(-) diff --git a/doc/contributing/docs/terms.rst b/doc/contributing/docs/terms.rst index c0bfbfdffc..968856a053 100644 --- a/doc/contributing/docs/terms.rst +++ b/doc/contributing/docs/terms.rst @@ -6,28 +6,29 @@ Defining and using terms What are concepts and terms --------------------------- -To write well about some subject matter, one needs to know the objects of this subject matter +To write well about a certain subject matter, +one needs to know the objects of this subject matter and use the right, carefully selected words for them. Such objects are called concepts, and the words for them are called terms. .. glossary:: concept - The concept is the idea of some object, attribute, or action. + A concept is the idea of some object, attribute, or action. It is independent of languages, audience, and products. It just exists. - For example, a large database can be partitioned into smaller instances, - which are easier to operate and can exceed the throughput of - a single large database instance. Such instances can exchange data - for keeping it consistent between them. + For example, a large database can be partitioned into smaller instances. + Those instances are easier to operate and can exceed the throughput of + a single large database instance. They can exchange data, + keeping it consistent between them. term - The term is a word, which authors or a particular book, article, or documentation set - have explicitly selected to denote a :term:`concept` in a particular language - and for a particular audience. + A term is a word explicitly selected by the authors of a particular text + to denote a :term:`concept` in a particular language + for a particular audience. For example, in Tarantool, we use the term "[database] sharding" to denote the - concept mentioned in the previous example. + concept described in the previous example. .. _use-preferred-terms: @@ -36,40 +37,40 @@ Use preferred terms ------------------- The purpose of using terms is to write concisely and unambiguously, -which is good for readers. +which is good for the readers. But selecting terms is hard. -Often there are two or more terms for one concept popular with the community, +Often, the community favors two or more terms for one concept, so there's no obvious choice. -Indeed, selecting and consistently using any of them is much better -than not selecting and just using random terms each time. +Selecting and consistently using any of them is much better +than not making a choice and using a random term every time. This is why it's also helpful to restrict the usage of some terms explicitly. .. glossary:: restricted term - A restricted term is a word that authors have explicitly forbidden to use for denoting a :term:`concept`. + A restricted term is a word that the authors explicitly prohibited to use for denoting a :term:`concept`. Such a word is sometimes used as a :term:`term` for the same :term:`concept` elsewhere: - in the community, in other books, or other products' documentation. + in the community, in books, or in other product documentation. Sometimes, this word is used to denote a similar but different concept. In this case, the right choice of terms helps us differentiate between concepts. For example, in Tarantool, we don't use the term "[database] segmentation" to denote what we call "database sharding." - Although, other authors could do so. - Also, there is the term "[database] partitioning" that we use to denote - a wider concept, which includes sharding and other things. + Nevertheless, other authors could do so. + We also use the term "[database] partitioning" to denote + a wider concept, which includes sharding among other things. .. _define-terms: Define terms by explaining concepts ----------------------------------- -Define the term by explaining the concept. -For the most important concepts and the ones unique to Tarantool, -the definition should always be in our documentation. +Definitions for the most important concepts, +as well as for concepts unique to Tarantool, +always have to be included in our documentation. -Define each term in the document which is most relevant to it. -There's no need to gather all definitions on a particular "Glossary" page. +Define every term in the document that you find most appropriate for it. +You don't have to create a dedicated glossary page with all the definitions. To define a term, use the ``glossary`` directive in the following way: @@ -91,15 +92,15 @@ This page has two of them, for example. The `Sphinx documentation `_ -has an extensive glossary, which we can use as a reference. +has an extensive glossary that can be used as a reference. .. _introduce-terms: Introduce terms on first entry ------------------------------ -When you use a term for the first time in a document, introduce it by giving a definition, -synonyms, translation, examples, and links. +When you use a term in a document for the first time, define it +and provide synonyms, a translation, examples, and/or links. It will help readers learn the term and understand the concept behind it. @@ -112,12 +113,12 @@ It will help readers learn the term and understand the concept behind it. .. code-block:: rst For example, this is a link to the definition of :term:`concept`. - As with any rST role, it can have :term:`custom text `. + Like any rST role, it can have :term:`custom text `. The resulting output will look like this: For example, this is a link to the definition of :term:`concept`. - As with any rST role, it can have :term:`custom text `. + Like any rST role, it can have :term:`custom text `. With acronyms, you can also use the `abbr` role: @@ -133,8 +134,8 @@ It will help readers learn the term and understand the concept behind it. Database sharding (also known as ...) is a type of... #. When writing in Russian, it's good to add the corresponding English term. - Readers may be more familiar with it or can use it in search. + Readers may be more familiar with it or can search it online. - Шардирование (сегментирование, sharding) — это... + Шардирование (сегментирование, sharding) --- это... #. Give examples or links to extra reading where you can. From 233360f97dc6515f73f7e9bf09ae4dbab9b37c8f Mon Sep 17 00:00:00 2001 From: patiencedaur Date: Fri, 13 Aug 2021 11:11:57 +0300 Subject: [PATCH 8/8] More proofreading --- doc/contributing/docs/examples.rst | 2 +- doc/contributing/docs/markup/links.rst | 10 ++++---- doc/contributing/docs/terms.rst | 33 +++++++++++++------------- 3 files changed, 23 insertions(+), 22 deletions(-) diff --git a/doc/contributing/docs/examples.rst b/doc/contributing/docs/examples.rst index 73c0eada1a..98012fdca9 100644 --- a/doc/contributing/docs/examples.rst +++ b/doc/contributing/docs/examples.rst @@ -12,9 +12,9 @@ Use this checklist for documenting a function or a method: * Return type (if exists) * Possible errors (if exist) * Complexity factors (if exist) +* Usage with memtx and vinyl (if differs) * Example(s) * Extra information (if needed) -.. // * Note re storage engine (if exists). TODO (was the third from last bullet point) Documenting functions ~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/contributing/docs/markup/links.rst b/doc/contributing/docs/markup/links.rst index 5f983ebfec..c42169c1fd 100644 --- a/doc/contributing/docs/markup/links.rst +++ b/doc/contributing/docs/markup/links.rst @@ -33,8 +33,8 @@ For this purpose, we add our own labels for linking to any place in this documen Our naming convention is as follows: -* Character set: a through z, 0 through 9, dash, underscore. -* Format: ``path dash filename dash tag`` +* Character set: a through z, 0 through 9, hyphen, underscore. +* Format: ``path hyphen filename hyphen tag`` **Example:** @@ -48,13 +48,13 @@ where: * ``box_index`` is the file name (without ".rst"), and * ``iterator_type`` is the tag. -Use a dash "-" to delimit the path and the file name. In the documentation -source, we use only underscores "_" in paths and file names, reserving dash "-" +Use a hyphen "-" to delimit the path and the file name. In the documentation +source, we use only underscores "_" in paths and file names, reserving the hyphen "-" as the delimiter for local links. The tag can be anything meaningful. The only guideline is for Tarantool syntax items (such as members), where the preferred tag syntax is -``module_or_object_name dash member_name``. For example, ``box_space-drop``. +``module_or_object_name hyphen member_name``. For example, ``box_space-drop``. To add a link to an anchor, use the following syntax: diff --git a/doc/contributing/docs/terms.rst b/doc/contributing/docs/terms.rst index 968856a053..c537c7e475 100644 --- a/doc/contributing/docs/terms.rst +++ b/doc/contributing/docs/terms.rst @@ -7,20 +7,20 @@ What are concepts and terms --------------------------- To write well about a certain subject matter, -one needs to know the objects of this subject matter +one needs to know its details and use the right, carefully selected words for them. -Such objects are called concepts, and the words for them are called terms. +These details are called concepts, and the words for them are called terms. .. glossary:: concept - A concept is the idea of some object, attribute, or action. + A concept is the idea of an object, attribute, or action. It is independent of languages, audience, and products. It just exists. For example, a large database can be partitioned into smaller instances. - Those instances are easier to operate and can exceed the throughput of - a single large database instance. They can exchange data, - keeping it consistent between them. + Those instances are easier to operate, and their throughput + often exceeds the throughput of a single large database instance. + The instances can exchange data to keep it consistent between them. term A term is a word explicitly selected by the authors of a particular text @@ -36,7 +36,7 @@ Such objects are called concepts, and the words for them are called terms. Use preferred terms ------------------- -The purpose of using terms is to write concisely and unambiguously, +The purpose of using terms is writing concisely and unambiguously, which is good for the readers. But selecting terms is hard. Often, the community favors two or more terms for one concept, @@ -48,15 +48,17 @@ This is why it's also helpful to restrict the usage of some terms explicitly. .. glossary:: restricted term - A restricted term is a word that the authors explicitly prohibited to use for denoting a :term:`concept`. - Such a word is sometimes used as a :term:`term` for the same :term:`concept` elsewhere: - in the community, in books, or in other product documentation. - Sometimes, this word is used to denote a similar but different concept. + A restricted term is a word that the authors explicitly + prohibited to use for denoting a :term:`concept`. + Such a word is sometimes used as a :term:`term` + for the same :term:`concept` elsewhere---in the + community, in books, or in other product documentation. + Sometimes this word is used to denote a similar but different concept. In this case, the right choice of terms helps us differentiate between concepts. For example, in Tarantool, we don't use the term "[database] segmentation" to denote what we call "database sharding." - Nevertheless, other authors could do so. + Nevertheless, other authors might do so. We also use the term "[database] partitioning" to denote a wider concept, which includes sharding among other things. @@ -65,12 +67,11 @@ This is why it's also helpful to restrict the usage of some terms explicitly. Define terms by explaining concepts ----------------------------------- -Definitions for the most important concepts, -as well as for concepts unique to Tarantool, -always have to be included in our documentation. +We always want to document definitions for the most important concepts, +as well as for concepts unique to Tarantool. Define every term in the document that you find most appropriate for it. -You don't have to create a dedicated glossary page with all the definitions. +You don't have to create a dedicated glossary page containing all the definitions. To define a term, use the ``glossary`` directive in the following way: