Update sphinx documentation

.github/CONTRIBUTING.md

@@ -0,0 +1,3 @@
+# Contributing
+
+Please refer to [Contribution guidelines](https://roc-streaming.org/toolkit/docs/development/contribution_guidelines.html) page for instructions!

docs/sphinx/about_project/contacts.rst

@@ -40,7 +40,3 @@ You can open the chat right in your browser using web links above, or you can `i
 .. note::
 
    You need to setup Matrix account to be able to join the room.
-
-.. note::
-
-   The formerly used IRC channel ``#rocstreaming`` at freenode is abandoned. Archives are `here <https://freenode.logbot.info/rocstreaming/>`_.

docs/sphinx/about_project/licensing.rst

@@ -3,4 +3,4 @@ Licensing
 
 Roc Toolkit source code is licensed under `MPL-2.0 <https://www.mozilla.org/en-US/MPL/2.0/>`_.
 
-If Roc Toolkit is built with OpenFEC support enabled, it must be distributed under a license compatible with `CeCILL <http://openfec.org/patents.html>`_, a GPL-like and GPL-compatible license used for OpenFEC.
+If Roc Toolkit is built with OpenFEC support enabled, it must be distributed under a license compatible with CeCCIL-C (LGPL-like license), if LDPC-Staircase codec is disabled, or CeCCIL (GPL-like license), if LDPC-Staircase codec is enabled. Refer to `OpenFEC website <http://openfec.org/patents.html>`_ for further details.

docs/sphinx/development/coding_guidelines.rst

@@ -8,16 +8,28 @@ Coding guidelines
 Language and libraries
 ======================
 
-* The codebase is mostly written in "C with classes", a simple and unsophisticated subset of C++.
-* We use C++98.
-* We don't use exceptions.
-* We mostly avoid templates.
-* We avoid inheritance, except "interface" inheritance.
-* We avoid operators, overloading, and default arguments.
-* We avoid using the preprocessor.
-* We don't use STL (the algorithms-and-containers part of the C++ standard library).
-* We don't use third-party utility libraries like Boost.
-* We maintain our own minimal utility library (roc_core) designed to be very lightweight and allowing fine-grained memory management.
+The usage of C++ in this project is quite specific. The codebase is primarily written in what we refer to as "C with classes", a simplified subset of C++ that intentionally omits several of its features:
+
+* No C++ features beyond C++98
+* No exceptions
+* No STL (the algorithms-and-containers part of the standard library)
+* Custom "core" library (roc_core)
+* Templates are mostly avoided (except utility classes in core)
+* Inheritance is primarily used only for "interface inheritance"
+* Overloading, operators, default arguments are avoided
+
+The roc_core library makes several essential design choices that differ significantly from STL:
+
+* it is small and lightweight
+* heavy operations, like deep copying or allocations, are never implicit
+* most operations include safety checks and will trigger a panic with stacktrace on incorrect usage
+* most containers are based on intrusive data structures
+* encourages fine-grained memory management based on arenas and pools
+* provides building blocks for lock-free programming
+
+These design choices render Roc codebase pretty unique and distinguish it from both plain C and modern C++.
+
+This approach may not be suitable for every project, but it appears to have been effective in the case of Roc due to its low-level, real-time nature, and at the same time the considerable size of its codebase.
 
 Portability
 ===========
@@ -33,7 +45,7 @@ Portability
 Best practices
 ==============
 
-* The code should compile without warnings (use ``--enable-werror`` SCons option).
+* The code should compile without warnings. Use ``--enable-werror`` :doc:`option </building/scons_options>` to turn warnings into errors.
 
 .. raw:: html
 
@@ -57,7 +69,7 @@ Best practices
 
     <span></span>
 
-* Use const when it is useful.
+* Use ``const`` when it's useful.
 
 .. raw:: html
 
@@ -81,13 +93,13 @@ Best practices
 
     <span></span>
 
-* Log (using ``roc_log``) important events and information needed to understand why an error occurred.
+* Carefully log (using ``roc_log``) all important events and information needed to understand why an error occurred.
 
 .. raw:: html
 
     <span></span>
 
-* Panic (using ``roc_panic``) when a contract or an invariant is broken. A panic is always preferred over a crash. However, remember that panics are only for bugs in Roc itself. Never panic on invalid or unexpected data from the outside world.
+* Panic (using ``roc_panic``) when a contract or an invariant is broken. A panic is always preferred over a crash or undefined behavior. However, remember that panics are only for bugs in Roc itself. Never panic on invalid or unexpected data from the outside world.
 
 Coding style
 ============
@@ -104,7 +116,7 @@ Coding style
 
     <span></span>
 
-* Headers, classes, public members, and free functions should be documented using Doxygen. If Doxygen is installed, it is invoked during build and warns about undocumented items.
+* Headers, classes, public members, and free functions should be documented using Doxygen. Use ``--enable-doxygen`` :doc:`option </building/scons_options>` to enable warnings about undocumented elements.
 
 .. raw:: html
 

docs/sphinx/development/contribution_guidelines.rst

@@ -5,79 +5,66 @@ Contribution guidelines
    :local:
    :depth: 1
 
-How you can help
-================
-
-If you would like to help the project, you can:
-
-* **help with testing**
-
-  Try to use Roc command-line tools or PulseAudio modules and report bugs or suggest improvements.
-
-* **help with research**
+Community
+=========
 
-  Discover how does Roc perform on different conditions and configurations and share the results. What latency and service quality does it provide in different cases, what parameter combinations are optimal, and so on.
+Welcome to join our Matrix chats and mailing list!
 
-* **help with porting**
+Please refer :doc:`this page </about_project/contacts>` for more details.
 
-  We'd be happy to meet developers who can help with maintaining ports for non-Linux \*nix systems, macOS, Android, Windows, and other platforms.
-
-* **contribute code**
-
-  Roc has quite a long and pretty interesting roadmap and a backlog with issues of varying difficulty. Read the documentation, choose a task, and submit pull requests!
-
-Choosing a task
-===============
+How you can help
+================
 
-Want to contribute code? Great! Here is how you can choose a task.
+* **Contributing code**
 
-.. note::
+  We are always looking for new contributors. Please refer to the section below for details on the onboarding process.
 
-   It is highly recommended to leave a comment on GitHub or throw a mail to the mailing list before starting working on an issue to ensure that nobody is already working on it.
+* **Testing**
 
-* **"help wanted" tag**
+  We'd appreciate help in testing new releases on your hardware and letting us know if you find any issues. We highly depend on feedback from users to identify bugs and receive suggestions for new features.
 
-  Look for issues marked with the `"help wanted" <https://github.com/roc-streaming/roc-toolkit/labels/help%20wanted>`_ tag. This tag means that this is an important and awaited task but we have no human resources for it yet, and it is still in the backlog.
+* **Writing tutorials**
 
-* **"easy hacks" tag**
+  If you've built Roc for a niche OS or hardware, or tweaked settings to make it work better for your needs, we'd love it if you share your experience with the community. If you've written a guide, you can send it to us to be added to the :doc:`publications page </about_project/publications>`.
 
-  Look for issues that are additionally marked with the `"easy hacks" <https://github.com/roc-streaming/roc-toolkit/labels/easy%20hacks>`_ tag. This tag means that the solution is expected to be straightforward even if you are new to the project.
+Becoming a contributor
+======================
 
-* **backlog column**
+First of all, thank you for your interest! We welcome and appreciate all help. Many important features were submitted by :doc:`numerous contributors </about_project/authors>`, and we are really grateful for that.
 
-  Look for issues in the "Backlog" column in the `project board <https://github.com/roc-streaming/roc-toolkit/projects/2>`_. Issues that are *not* marked as "help wanted" are probably not very good for you if you're new to the project, but you can take your chances if you would like to.
+The guide bellow will help you to prepare your first patch.
 
-* **project roadmap**
+* **Step 1: Checkout and build project**
 
-  Look for unimplemented features in the long-term :doc:`project roadmap </development/roadmap>`. If there is no issue for a feature yet, it means that nobody had thought through it yet. You are suggested to open an issue for discussion in this case.
+  Build instructions can be found here:
 
-* **suggest your own**
+  * :doc:`/building/user_cookbook`
+  * :doc:`/building/developer_cookbook`
 
-  Of course, you're also welcome to open an issue and suggest a feature that is not in our backlog and roadmap.
+* **Step 2: Get introduced to project internals**
 
-Working on a patch
-==================
+  Take a look at documentation of :doc:`project internals </internals>`.
 
-If you have chosen a task and are ready to work on it, the following documentation is your friend:
+  There is also Doxygen-generated documentation for `internal modules <https://roc-streaming.org/toolkit/doxygen/>`_.
 
-* **project internals**
+* **Step 3: Learn coding guidelines**
 
-  See :doc:`/internals` section for a high-level overview.
+  Please refer to this page: :doc:`/development/coding_guidelines`.
 
-  See also more low-level `Doxygen-generated documentation <https://roc-streaming.org/toolkit/doxygen/>`_.
+* **Step 4: Choose a task**
 
-* **coding guidelines**
+  Tasks needing assistance are marked with `"help wanted" <https://github.com/roc-streaming/roc-toolkit/labels/help%20wanted>`_ label. These tasks usually come with detailed explanations and are suitable for newcomers.
 
-  Please take a look at the :doc:`/development/coding_guidelines` page. The guidelines are not hard to follow but some of them a specific.
+  Some of these tasks are also labeled as `"easy hacks" <https://github.com/roc-streaming/roc-toolkit/labels/easy%20hacks>`_. It indicates that the solution is expected to be pretty straightforward, making them a good entry point to the project.
 
-* **version control**
+  Extra labels make it easier to find various kinds of problems, like "tests," "refactoring," "algorithms," "networking," and more.
 
-  Please also take a look at the :doc:`/development/version_control` page for details on commits, branches, and pull requests.
+  When you pick a task, please leave a comment to let others know so that we don't end up with multiple people doing the same thing. If a task hasn't been assigned, it usually means no one is currently working on it.
 
-* **asking questions**
+* **Step 5: Create pull request!**
 
-  Feel free to ask questions on our mailing list or Matrix chat. See :doc:`/about_project/contacts` page for details.
+  Please remember that pull requests should be always rebased on ``develop`` branch and should be targeted to it, as :doc:`described here </development/version_control>`.
 
-* **getting credits**
+  Before submitting PR, don't forget to run code formatting, as described in coding guidelines.
 
-  Feel free to add yourself to the :doc:`/about_project/authors` page when submitting a patch. It is updated from git log from time to time.
+  Please ensure that all CI checks pass on your PR and fix them if needed.