Code autogenerated from Kurento/doc-kurento@2cb3cd3

README.md

@@ -18,6 +18,8 @@ doc-kurento
 
 Kurento Documentation. Made with [Sphinx] and [Read the Docs].
 
+To learn the style conventions and how to build these docs, read here: [Writing this documentation](https://doc-kurento.readthedocs.io/en/latest/dev/writing_documentation.html).
+
 [Sphinx]: https://www.sphinx-doc.org/
 [Read the Docs]: https://docs.readthedocs.io
 

requirements.txt

@@ -2,8 +2,12 @@
 # https://pip.pypa.io/en/latest/user_guide/#requirements-files
 #
 # Usage:
-#     $ pip3 install --upgrade -r requirements.txt
-#     $ export PATH="$HOME/.local/bin:$PATH"
+#     # Create and load the Python virtual environment
+#     python3 -m venv python_modules
+#     source python_modules/bin/activate
+#
+#     # Install Sphinx and the Read the Docs theme
+#     python -m pip install --upgrade -r requirements.txt
 
 Sphinx~=3.5.4
 sphinx-rtd-theme~=0.5.2

source/dev/dev_guide.rst

@@ -174,7 +174,7 @@ This command will install the basic set of tools that are needed for the next st
 
 .. code-block:: shell
 
-   sudo apt-get update && sudo apt-get install --no-install-recommends --yes \
+   sudo apt-get update && sudo apt-get install --no-install-recommends \
        build-essential \
        ca-certificates \
        cmake \
@@ -213,7 +213,7 @@ Run:
 
 .. code-block:: shell
 
-   sudo apt-get update && sudo apt-get install --no-install-recommends --yes \
+   sudo apt-get update && sudo apt-get install --no-install-recommends \
        kurento-media-server-dev
 
 
@@ -265,7 +265,9 @@ You can set the logging level of specific categories by exporting the environmen
 Clean up your system
 --------------------
 
-To leave the system in a clean state, remove all KMS packages and related development libraries. Run this command and, for each prompted question, visualize the packages that are going to be uninstalled and press Enter if you agree. This command is used on a daily basis by the development team at Kurento with the option ``--yes`` (which makes the process automatic and unattended), so it should be fairly safe to use. However we don't know what is the configuration of your particular system, and running in manual mode is the safest bet in order to avoid uninstalling any unexpected package.
+To leave the system in a clean state, remove all KMS packages and related development libraries.
+
+This command should be fairly safe to use; it works perfectly fine for us on a daily basis (we even use it with the option ``--yes``, which makes the process automatic and unattended). Still, please carefully review the list of packages marked for uninstalling.
 
 Run:
 
@@ -330,7 +332,7 @@ Now, install all debug symbols that are relevant to KMS:
 
 .. code-block:: shell
 
-   sudo apt-get update && sudo apt-get install --no-install-recommends --yes \
+   sudo apt-get update && sudo apt-get install --no-install-recommends \
        kurento-dbg
 
 

source/dev/release.rst

@@ -296,7 +296,7 @@ Test the KMS API Java module generation (local check).
 
 .. code-block:: shell
 
-   apt-get update && apt-get install --no-install-recommends --yes \
+   apt-get update && apt-get install --no-install-recommends \
        kurento-module-creator \
        kms-cmake-utils \
        kms-jsonrpc-dev \

source/dev/writing_documentation.rst

@@ -4,19 +4,17 @@ Writing this documentation
 
 .. contents:: Table of Contents
 
-Although each of the Kurento repositories contains a *README* file, the main source of truth for up-to-date information about Kurento is *this* documentation you are reading right now, hosted at Read the Docs.
+Although each of the Kurento repositories contains a *README* file, the main source of truth for up-to-date information about Kurento is *this* documentation you are reading right now. This is done in a 3 steps process:
 
-The final deliverable form of the documentation is obtained by following a 3-step process:
+1. Sources are written in a markup language called `reStructuredText <https://docutils.sourceforge.io/rst.html>`__ (or **reST**, for short). This format is less known that the popular `Markdown <https://www.markdownguide.org/getting-started/>`__, but it is much more powerful and adequate for long-form documentation writing.
 
-1. Documentation sources are written in a markup language called `reStructuredText <https://docutils.sourceforge.io/rst.html>`__ (or **reST**, for short). This format is less known that the popular `Markdown <https://www.markdownguide.org/getting-started/>`__, but it is much more powerful and adequate for long-form documentation writing.
+   To learn the *reST* language have a look at the `Sphinx guide to reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`__ and the official `Quick reStructuredText <https://docutils.sourceforge.io/docs/user/rst/quickref.html>`__ reference.
 
-   The *reST* language itself can be learned from pages such as the `Sphinx guide to reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`__ of the official `Quick reStructuredText <https://docutils.sourceforge.io/docs/user/rst/quickref.html>`__ reference.
+2. `Sphinx <https://www.sphinx-doc.org/>`__ is used to convert the *reST* files into the final output formal, such as HTML or PDF.
 
-2. The *reST* source files are processed and converted to other deliverable formats (such as HTML or PDF) by `Sphinx <https://www.sphinx-doc.org/>`__, a documentation processing tool.
+3. The resulting files are hosted in `Read the Docs <https://docs.readthedocs.io/>`__.
 
-3. Finally, the generated files are hosted in `Read the Docs <https://docs.readthedocs.io/>`__, the service of choice for lots of Open Source projects. Actually Read the Docs is not only the hosting, but they also perform the Sphinx generation step itself: they have a Continuous Integration system that watches our Git repository and triggers a new documentation build each time a change is pushed.
-
-Sphinx is able to extend the core *reST* language by means of *extensions*, and we use some of them:
+The core *reST* language is extended by Sphinx by means of *extensions*, and we use some of them:
 
 * `sphinx.ext.extlinks <https://www.sphinx-doc.org/en/3.x/usage/extensions/extlinks.html>`__, to easily provide links to external sites (currently for the `English Wikipedia <https://en.wikipedia.org/>`__).
 * `sphinx.ext.graphviz <https://www.sphinx-doc.org/en/3.x/usage/extensions/graphviz.html>`__, to embed `Graphviz <https://graphviz.org/>`__ DOT diagrams.
@@ -27,50 +25,72 @@ Sphinx is able to extend the core *reST* language by means of *extensions*, and
 Building locally
 ================
 
-If you are writing documentation for Kurento, there is no need to commit every change and push to see the result only to discover that an image doesn't show up as you expected, or some small mistake breaks a table layout.
-
-First of all, it's a very good idea to use a text editor that provides spell checking and live-preview visualization of *reST* files; this alone will help catching most grammatical and syntactic mistakes. `Visual Studio Code <https://code.visualstudio.com/>`__ is a great option, it provides extensions for both of these things.
+Check spelling
+--------------
 
-To install the two mentioned features for *VSCode*, run these commands:
+Please use a text editor that provides spell checking and live-preview visualization of *reST* files; this alone will help catching most grammatical and syntactic mistakes. `Visual Studio Code <https://code.visualstudio.com/>`__ is a great option, it provides extensions for both of these things:
 
 .. code-block:: shell
 
    code --install-extension streetsidesoftware.code-spell-checker
    code --install-extension lextudio.restructuredtext
 
-To install Sphinx, first ensure that your system has Python 3 and the *pip* installer available. Do not run this command if you know that your system is already configured with these tools:
+
+
+Install dependencies
+--------------------
+
+You'll need these tools:
+
+* Python 3, including:
+
+  - The *PIP* package installer, used to install Sphinx.
+  - Optionally, but strongly recommended, the Python's virtual env tool.
+
+* Graphviz, to convert ``.dot`` files into graphs.
 
 .. code-block:: shell
 
-   # Install Python 3 and the pip installer
-   sudo apt-get update && sudo apt-get install --no-install-recommends --yes \
-       python3 python3-pip
+   sudo apt-get update && sudo apt-get install --no-install-recommends \
+       python3 python3-pip python3-venv \
+       graphviz
 
-Also optionally, make a bit of cleanup in case old versions were installed:
+Optionally, make a bit of cleanup in case old Sphinx versions were installed:
 
 .. code-block:: shell
 
    # Ensure that old versions of Sphinx are not installed
-   sudo apt-get purge --auto-remove --yes \
+   sudo apt-get purge --auto-remove \
        '^python-sphinx.*' \
        '^python3-sphinx.*' \
        '^sphinx.*'
 
-   pip3 freeze | grep -i '^sphinx' | xargs sudo -H pip3 uninstall --yes
+   pip3 freeze | grep -i '^sphinx' | xargs sudo -H pip3 uninstall
 
-And finally, perform the installation:
+And finally, install Sphinx:
 
 .. code-block:: shell
 
+   # Create and load the Python virtual environment
+   python3 -m venv python_modules
+   source python_modules/bin/activate
+
    # Install Sphinx and the Read the Docs theme
-   pip3 install --upgrade -r requirements.txt
-   export PATH="$HOME/.local/bin:$PATH"
+   python -m pip install --upgrade -r requirements.txt
 
-Now just run ``make html`` inside the documentation directory, and open the newly built files with a web browser:
+
+
+Build docs
+----------
+
+Run ``make html`` inside the documentation directory, and open the newly built files with a web browser:
 
 .. code-block:: shell
 
-   cd doc-kurento/
+   # Load the Python virtual environment
+   source python_modules/bin/activate
+
+   # Build and open the documentation files
    make html
    firefox build/html/index.html
 
@@ -82,33 +102,37 @@ Kurento documentation Style Guide
 Paragraph conventions
 ---------------------
 
-* **Line breaks**: *Don't* break the lines. The documentation is a prose text, and not source code, so the typical restrictions of line length don't apply here. Use automatic line breaks in your editor, if you want. The overall flow of the text should be dictated by the width of the screen where the text is being presented, and not by some arbitrary line length limit.
+* **Line breaks**: *Don't* break the lines. Documentation is prose text, and not source code, so the typical code line length limit rules don't make any sense and don't apply here.
 
 
 
 Inline markup
 -------------
 
-* File names, package names, variable names, class and event names, (mostly all kinds of names), acronyms, commit hashes, and in general any kind of identifier which could be broken into different lines are emphasized with single asterisks (as in ``*word*``). Sample phrases:
-
-  .. code-block:: text
+* Names, acronyms, and in general any kind of referential name should be emphasized with single asterisks (as in ``*word*``).
 
-     This document talks about Kurento Media Server (*KMS*).
-     All dependency targets are defined in the *CMakeLists.txt* file.
-     You need to install *libboost-dev* for development.
-     Enable debug by setting the *GST_DEBUG* environment variable.
+* File names, full paths, URLs, package names, variable names, class and event names, code samples, commands, and in general any machine-oriented keywords, must be written inside double back-quotes (as in ````word````). This formatting *prevents line breaking*, which tends to be desirable for these kinds of technical words.
 
-* Paths, URLs, code samples, commands, and in general any machine-oriented keywords are emphasized with double back quotes (as in ````word````). This formatting stands out, and most importantly *it cannot be broken into different lines*. Sample phrases:
+Sample phrases:
 
   .. code-block:: text
 
+     This document talks about Kurento Media Server (*KMS*).
+     All dependency targets are defined in the ``CMakeLists.txt`` file.
+     You need to install ``libboost-dev`` for development.
+     Enable debug by setting the ``GST_DEBUG`` environment variable.
+
      Use ``apt-get install`` to set up all required packages.
      Set ``CMAKE_BUILD_TYPE=Debug`` to build with debug symbols.
      The argument ``--gst-debug`` can be used to control the logging level.
 
-* There is no difference between using *single asterisks* (``*word*``), and `single back quotes` (```word```); they get rendered as *italic text*. So, always use asterisks when wanting to emphasize some text.
+Important differences between *reST* and *Markdown*:
+
+* *reST* uses **two back-quotes** for inline code, not one. It is ````word````, not ```word```.
+
+* *reST* renders *single asterisks* (``*word*``) and `single back-quotes` (```word```) as *italic text*. For this reason, it's better to always use asterisks for emphasizing, to avoid confusing people who come from Markdown.
 
-* As opposed to Markdown, underscores (as in ``_word_``) *don't get rendered*, so don't use them to emphasize text.
+* *reST* does *not* render underscores (as in ``_word_``), so don't use them to emphasize text.
 
 
 

source/features/kurento_protocol.rst

@@ -719,7 +719,7 @@ Kurento Module Creator can be installed in an Ubuntu machine using the  followin
 
 .. code-block:: shell
 
-   sudo apt-get update && sudo apt-get install --yes kurento-module-creator
+   sudo apt-get update && sudo apt-get install kurento-module-creator
 
 The aim of this tool is to generate the client code and also the glue code
 needed in the server-side. For code generation it uses `Freemarker <https://freemarker.apache.org/>`__ as the template engine. The typical way to use Kurento Module Creator is by running a command like this:

source/features/logging.rst

@@ -56,28 +56,39 @@ Transcoding of media
 WebRtcEndpoint and RtpEndpoint
 ------------------------------
 
-.. code-block:: shell
+* To show all state changes (*MediaFlowIn*, *MediaFlowOut*, *MediaTranscoding*, etc):
+
+  .. code-block:: shell
+
+     export GST_DEBUG="${GST_DEBUG:-2},Kurento*:5,KurentoWebSocket*:4"
 
-   export GST_DEBUG="${GST_DEBUG:-2},Kurento*:5,KurentoWebSocket*:4"
-   export GST_DEBUG="${GST_DEBUG:-2},kmssdpsession:5"
-   export GST_DEBUG="${GST_DEBUG:-2},sdp*:5"
-   export GST_DEBUG="${GST_DEBUG:-2},webrtcendpoint:5,kmswebrtcsession:5,kmsiceniceagent:5"
+* To show high-level debug messages of SDP processing in KMS (SDP Offer/Answer negotiation). In most situations this is the level you want to enable for troubleshooting issues with SDP:
 
-* "Kurento*:5" shows all state changes (*MediaFlowIn*, *MediaFlowOut*, *MediaTranscoding*, etc). Use "KurentoWebSocket*:4" to avoid getting all verbose logs about the WebSocket communications.
-* "kmssdpsession:5" prints the SDP messages (SDP Offer/Answer negotiation) processed by KMS.
-* "sdp*:5" shows internal messages related to the construction of SDP messages and media handlers.
+  .. code-block:: shell
+
+     export GST_DEBUG="${GST_DEBUG:-2},kmssdpsession:5"
 
-* "webrtcendpoint:5", "kmswebrtcsession:5", and "kmsiceniceagent:5" all contain the logic that governs ICE gathering and ICE candidate selection for WebRTC.
+* For more verbose, low-level information about all SDP handling. Usually this is not needed except for the most advanced analysis of SDP issues:
+
+  .. code-block:: shell
+
+     export GST_DEBUG="${GST_DEBUG:-2},sdp*:5,basesdpendpoint:5"
+
+* To show the logic that governs ICE gathering and ICE candidate selection for WebRTC:
+
+  .. code-block:: shell
+
+     export GST_DEBUG="${GST_DEBUG:-2},webrtcendpoint:5,kmswebrtcsession:5,kmsiceniceagent:5"
 
   .. note::
 
      See also :ref:`logging-libnice` to enable advanced :term:`ICE` logging for WebRTC.
 
-You can also see messages about the :term:`REMB` congestion control algorithm for WebRTC. However these will constantly be filling the log, so you shouldn't enable them unless explicitly working out an issue with REMB:
+* Lastly, to see messages about the :term:`REMB` congestion control algorithm (adaptive video bitrate) for WebRTC. These will constantly be filling the log, so you shouldn't enable them unless explicitly working out an issue with REMB:
 
-.. code-block:: shell
+  .. code-block:: shell
 
-   export GST_DEBUG="${GST_DEBUG:-2},KurentoBaseRtpEndpointImpl:5,basertpendpoint:5,kmsremb:5"
+     export GST_DEBUG="${GST_DEBUG:-2},KurentoBaseRtpEndpointImpl:5,basertpendpoint:5,kmsremb:5"
 
 
 

source/features/security.rst

@@ -108,7 +108,7 @@ WebRTC requires HTTPS, so your JavaScript application must be served by a secure
 .. code-block:: shell
 
    curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
-   sudo apt-get install --yes nodejs
+   sudo apt-get install nodejs
    sudo npm install -g http-server
 
 * Obtain a certificate. For this, either request one from a trusted Certification Authority (*CA*), or generate your own one as explained here: :doc:`/knowledge/selfsigned_certs`.
@@ -222,11 +222,20 @@ Make sure your application uses a WebSocket URL that starts with ``wss://`` inst
 
 
 
+.. _features-security-kms-dtls:
+
 Media Plane security (DTLS)
 ---------------------------
 
-WebRTC uses :wikipedia:`DTLS <Datagram_Transport_Layer_Security>` for media data authentication. By default, if no certificate is provided for this, Kurento Media Server will auto-generate its own self-signed certificate for every WebRtcEndpoint instance, but it is also possible to provide an already existing certificate to be used for all endpoints.
+WebRTC uses :wikipedia:`DTLS <Datagram_Transport_Layer_Security>` for media data authentication. By default, if no certificate is provided for this, Kurento Media Server will auto-generate a new self-signed certificate for every WebRtcEndpoint instance.
+
+Alternatively, an already existing certificate can be provided to be used for all endpoints. For this, edit the file ``/etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini`` and set either *pemCertificateRSA* or *pemCertificateECDSA* with a file containing both your certificate (chain) file(s) and the private key. You can generate such file with the ``cat`` command:
+
+.. code-block:: shell
+
+   # Make a single file to be used with Kurento Media Server.
+   cat cert.pem key.pem > cert+key.pem
 
-To do so, edit the file ``/etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini`` and set either *pemCertificateRSA* or *pemCertificateECDSA* with a file containing the concatenation of your certificate (chain) file(s) and the private key.
+Then, :ref:`configure <configuration-dtls>` the path to ``cert+key.pem``.
 
 Setting a custom certificate for DTLS is needed, for example, for situations where you have to manage multiple media servers and want to make sure that all of them use the same certificate for their connections. Some browsers, such as Firefox, require this in order to allow multiple WebRTC connections from the same tab to different KMS instances.

source/knowledge/memory_fragmentation.rst

@@ -41,7 +41,7 @@ First install it on your system. For the versions of Ubuntu that are explicitly
 
 .. code-block:: shell
 
-   sudo apt-get update && sudo apt-get install --yes libjemalloc1
+   sudo apt-get update && sudo apt-get install libjemalloc1
 
 Jemalloc is installed as a standalone library. To actually use it, you need to preload it when launching KMS:
 

source/knowledge/nat.rst

@@ -295,7 +295,7 @@ PyNAT
 
 .. code-block:: shell
 
-   sudo apt-get update && sudo apt-get install --no-install-recommends --yes \
+   sudo apt-get update && sudo apt-get install --no-install-recommends \
        python3 python3-pip
 
    sudo -H pip3 install --upgrade pynat

source/knowledge/rtp_streaming.rst

@@ -14,7 +14,7 @@ To run these examples, follow these initial steps:
 
    .. code-block:: shell
 
-      sudo apt-get update && sudo apt-get install --no-install-recommends --yes \
+      sudo apt-get update && sudo apt-get install --no-install-recommends \
           gstreamer1.0-{tools,libav} \
           gstreamer1.0-plugins-{base,good,bad,ugly}
 
@@ -348,7 +348,7 @@ For the SRTP examples, you need to install the Kurento's fork of GStreamer:
 
 .. code-block:: shell
 
-   sudo apt-get update && sudo apt-get install --no-install-recommends --yes \
+   sudo apt-get update && sudo apt-get install --no-install-recommends \
        gstreamer1.5-{tools,libav} \
        gstreamer1.5-plugins-{base,good,bad,ugly}