Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

11 files changed, 328 insertions, 0 deletions

diff --git a/tools/moztreedocs/docs/adding-documentation.rst b/tools/moztreedocs/docs/adding-documentation.rst
new file mode 100644
index 0000000000..9abb6a2f84
--- /dev/null
+++ b/tools/moztreedocs/docs/adding-documentation.rst
@@ -0,0 +1,30 @@
+Adding Documentation
+--------------------
+
+To add new documentation, define the ``SPHINX_TREES`` and
+``SPHINX_PYTHON_PACKAGE_DIRS`` variables in ``moz.build`` files in
+the tree and documentation will automatically get picked up.
+
+Say you have a directory ``featureX`` you would like to write some
+documentation for. Here are the steps to create Sphinx documentation
+for it:
+
+1. Create a directory for the docs. This is typically ``docs``. e.g.
+   ``featureX/docs``.
+2. Create an ``index.rst`` file in this directory. The ``index.rst`` file
+   is the root documentation for that section. See ``build/docs/index.rst``
+   for an example file.
+3. In a ``moz.build`` file (typically the one in the parent directory of
+   the ``docs`` directory), define ``SPHINX_TREES`` to hook up the plumbing.
+   e.g. ``SPHINX_TREES['featureX'] = 'docs'``. This says *the ``docs``
+   directory under the current directory should be installed into the
+   Sphinx documentation tree under ``/featureX``*.
+4. If you have Python packages you would like to generate Python API
+   documentation for, you can use ``SPHINX_PYTHON_PACKAGE_DIRS`` to
+   declare directories containing Python packages. e.g.
+   ``SPHINX_PYTHON_PACKAGE_DIRS += ['mozpackage']``.
+5. In ``docs/config.yml``, defines in which category the doc
+   should go.
+6. Verify the rst syntax using `./mach lint -l rst`_
+
+.. _./mach lint -l rst: /tools/lint/linters/rstlinter.html
diff --git a/tools/moztreedocs/docs/architecture.rst b/tools/moztreedocs/docs/architecture.rst
new file mode 100644
index 0000000000..fc502f847f
--- /dev/null
+++ b/tools/moztreedocs/docs/architecture.rst
@@ -0,0 +1,51 @@
+Documentation architecture
+==========================
+
+The documentation relies on Sphinx and many Sphinx extensions.
+
+The documentation code is in two main directories:
+
+* https://searchfox.org/mozilla-central/source/docs
+* https://searchfox.org/mozilla-central/source/tools/moztreedocs
+
+Our documentation supports both rst & markdown syntaxes.
+
+Configuration
+-------------
+
+The main configuration file is:
+
+https://searchfox.org/mozilla-central/source/docs/config.yml
+
+It contains the categories, the redirects, the warnings and others configuration aspects.
+
+The dependencies are listed in:
+
+https://searchfox.org/mozilla-central/source/tools/moztreedocs/requirements.in
+
+Be aware that Python libraries stored in `third_party/python` are used in priority (not always for good reasons). See :ref:`Vendor the source of the Python package in-tree <python-vendor>` for more details.
+
+
+Architecture
+------------
+
+
+`mach_commands <https://searchfox.org/mozilla-central/source/tools/moztreedocs/mach_commands.py>`__
+contains:
+
+* `mach doc` arguments managements
+* Detection/configuration of the environment (nodejs for jsdoc, pip for dependencies, etc)
+* Symlink the doc sources (.rst & .md) from the source tree into the staging directory
+* Fails the build if any critical warnings have been identified
+* Starts the sphinx build (and serve it if the option is set)
+* Manages telemetry
+
+`docs/conf.py <https://searchfox.org/mozilla-central/source/docs/conf.py>`__ defines:
+
+* The list of extensions
+* JS source paths
+* Various sphinx configuration
+
+At the end of the build documentation process, files will be uploaded to a CDN:
+
+https://searchfox.org/mozilla-central/source/tools/moztreedocs/upload.py
diff --git a/tools/moztreedocs/docs/index.rst b/tools/moztreedocs/docs/index.rst
new file mode 100644
index 0000000000..fc03756fbe
--- /dev/null
+++ b/tools/moztreedocs/docs/index.rst
@@ -0,0 +1,24 @@
+Managing Documentation
+======================
+
+Documentation is hard. It's difficult to write, difficult to find and always out
+of date. That's why we implemented our in-tree documentation system that
+underpins firefox-source-docs.mozilla.org. The documentation lives next to the
+code that it documents, so it can be updated within the same commit that makes
+the underlying changes.
+
+This documentation is generated via the
+`Sphinx <http://sphinx-doc.org/>`_ tool from sources in the tree.
+
+To build the documentation, run ``mach doc``. Run
+``mach help doc`` to see configurable options.
+
+The review group in Phabricator is ``#firefox-source-docs-reviewers``.
+For simple documentation changes, reviews are not required.
+
+.. toctree::
+  :caption: Documentation
+  :maxdepth: 2
+  :glob:
+
+  *
diff --git a/tools/moztreedocs/docs/jsdoc-support.rst b/tools/moztreedocs/docs/jsdoc-support.rst
new file mode 100644
index 0000000000..100fb92dac
--- /dev/null
+++ b/tools/moztreedocs/docs/jsdoc-support.rst
@@ -0,0 +1,16 @@
+jsdoc support
+=============
+
+Here is a quick example, for the public AddonManager :ref:`API <AddonManager Reference>`
+
+To use it for your own code:
+
+#. Check that JSDoc generates the output you expect (you may need to use a @class annotation on "object initializer"-style class definitions for instance)
+
+#. Create an `.rst file`, which may contain explanatory text as well as the API docs. The minimum will look something like
+    `this <https://firefox-source-docs.mozilla.org/_sources/toolkit/mozapps/extensions/addon-manager/AddonManager.rst.txt>`__
+
+#. Ensure your component is on the js_source_path here in the sphinx
+    config: https://hg.mozilla.org/mozilla-central/file/72ee4800d415/tools/docs/conf.py#l46
+
+#. Run `mach doc` locally to generate the output and confirm that it looks correct.
diff --git a/tools/moztreedocs/docs/mdn-import.rst b/tools/moztreedocs/docs/mdn-import.rst
new file mode 100644
index 0000000000..69d2f56df4
--- /dev/null
+++ b/tools/moztreedocs/docs/mdn-import.rst
@@ -0,0 +1,34 @@
+Importing documentation from MDN
+--------------------------------
+
+As MDN should not be used for documenting mozilla-central specific code or process,
+the documentation should be migrated in this repository.
+
+The meta bug is `Bug 1617963 <https://bugzilla.mozilla.org/show_bug.cgi?id=migrate-from-mdn>`__.
+
+Fortunately, there is an easy way to import the doc from MDN using GitHub
+to the firefox source docs.
+
+1. Install https://pandoc.org/ - If you are using packages provided by your distribution,
+   make sure that the version is not too old.
+
+2. Identify where your page is located on the GitHub repository ( https://github.com/mdn/archived-content/tree/main/files/en-us/mozilla ).
+   Get the raw URL
+
+3. Run pandoc the following way:
+
+.. code-block:: shell
+
+   $ pandoc -t rst https://github.com/mdn/archived-content/tree/main/files/en-us/mozilla/firefox/performance_best_practices_for_firefox_fe_engineers > doc.rst
+
+4. In the new doc.rst, identify the images and wget/curl them into `img/`.
+
+5. Verify the rst syntax using `./mach lint -l rst`_
+
+.. _./mach lint -l rst: /tools/lint/linters/rstlinter.html
+
+6. If relevant, remove unbreakable spaces (rendered with a "!" on Phabricator)
+
+.. code-block:: shell
+
+   $ sed -i -e 's/\xc2\xa0/ /g' doc.rst
diff --git a/tools/moztreedocs/docs/mermaid-integration.rst b/tools/moztreedocs/docs/mermaid-integration.rst
new file mode 100644
index 0000000000..ec0da3dd74
--- /dev/null
+++ b/tools/moztreedocs/docs/mermaid-integration.rst
@@ -0,0 +1,104 @@
+Mermaid Integration
+===================
+
+Mermaid is a tool that lets you generate flow charts, sequence diagrams, gantt
+charts, class diagrams and vcs graphs from a simple markup language. This
+allows charts and diagrams to be embedded and edited directly in the
+documentation source files rather than creating them as images using some
+external tool and checking the images into the tree.
+
+To add a diagram, simply put something like this into your page:
+
+.. These two examples come from the upstream website (https://mermaid-js.github.io/mermaid/#/)
+
+.. code-block:: rst
+    :caption: .rst
+
+    .. mermaid::
+
+        graph TD;
+            A-->B;
+            A-->C;
+            B-->D;
+            C-->D;
+
+.. code-block:: md
+    :caption: .md
+
+    ```{mermaid}
+    graph TD;
+        A-->B;
+        A-->C;
+        B-->D;
+        C-->D;
+    ```
+
+The result will be:
+
+.. mermaid::
+
+     graph TD;
+         A-->B;
+         A-->C;
+         B-->D;
+         C-->D;
+
+Or
+
+.. code-block:: rst
+    :caption: .rst
+
+    .. mermaid::
+
+         sequenceDiagram
+             participant Alice
+             participant Bob
+             Alice->>John: Hello John, how are you?
+             loop Healthcheck
+                 John->>John: Fight against hypochondria
+             end
+             Note right of John: Rational thoughts <br/>prevail!
+             John-->>Alice: Great!
+             John->>Bob: How about you?
+             Bob-->>John: Jolly good!
+
+.. code-block:: markdown
+    :caption: .md
+
+    ```{mermaid}
+    sequenceDiagram
+        participant Alice
+        participant Bob
+        Alice->>John: Hello John, how are you?
+        loop Healthcheck
+            John->>John: Fight against hypochondria
+        end
+        Note right of John: Rational thoughts <br/>prevail!
+        John-->>Alice: Great!
+        John->>Bob: How about you?
+        Bob-->>John: Jolly good!
+    ```
+
+
+
+will show:
+
+.. mermaid::
+
+     sequenceDiagram
+         participant Alice
+         participant Bob
+         Alice->>John: Hello John, how are you?
+         loop Healthcheck
+             John->>John: Fight against hypochondria
+         end
+         Note right of John: Rational thoughts <br/>prevail!
+         John-->>Alice: Great!
+         John->>Bob: How about you?
+         Bob-->>John: Jolly good!
+
+
+See `Mermaid's official <https://mermaid-js.github.io/mermaid/#/>`__ docs for
+more details on the syntax, and use the
+`Mermaid Live Editor <https://mermaidjs.github.io/mermaid-live-editor/>`__ to
+experiment with creating your own diagrams.
diff --git a/tools/moztreedocs/docs/nested-docs.rst b/tools/moztreedocs/docs/nested-docs.rst
new file mode 100644
index 0000000000..e2eb03b42d
--- /dev/null
+++ b/tools/moztreedocs/docs/nested-docs.rst
@@ -0,0 +1,14 @@
+Nested Doc Trees
+================
+
+This feature essentially means we can now group related docs together under
+common "landing pages". This will allow us to refactor the docs into a structure that makes more sense. For example we could have a landing page for docs describing Gecko's internals, and another one for docs describing developer workflows in `mozilla-central`.
+
+
+To clarify a few things:
+
+#. The path specified in `SPHINX_TREES` does not need to correspond to a path in `mozilla-central`. For example, I could register my docs using `SPHINX_TREES["/foo"] = "docs"`, which would make that doc tree accessible at `firefox-source-docs.mozilla.org/foo`.
+
+#. Any subtrees that are nested under another index will automatically be hidden from the main index. This means you should make sure to link to any subtrees from somewhere in the landing page. So given my earlier doc tree at `/foo`, if I now created a subtree and registered it using `SPHINX_TREES["/foo/bar"] = "docs"`, those docs would not show up in the main index.
+
+#. The relation between subtrees and their parents does not necessarily have any bearing with their relation on the file system. For example, a doc tree that lives under `/devtools` can be nested under an index that lives under `/browser`.
diff --git a/tools/moztreedocs/docs/redirect.rst b/tools/moztreedocs/docs/redirect.rst
new file mode 100644
index 0000000000..6ec29cdfd0
--- /dev/null
+++ b/tools/moztreedocs/docs/redirect.rst
@@ -0,0 +1,11 @@
+Redirects
+=========
+
+We now have the ability to define redirects in-tree! This will allow us to
+refactor and move docs around to our hearts content without needing to worry
+about stale external URLs. To set up a redirect simply add a line to this file under ``redirects`` key:
+
+https://searchfox.org/mozilla-central/source/docs/config.yml
+
+Any request starting with the prefix on the left, will be rewritten to the prefix on the right by the server. So for example a request to
+``/testing/marionette/marionette/index.html`` will be re-written to ``/testing/marionette/index.html``. Amazon's API only supports prefix redirects, so anything more complex isn't supported.
diff --git a/tools/moztreedocs/docs/rstlint.rst b/tools/moztreedocs/docs/rstlint.rst
new file mode 100644
index 0000000000..230ba2e812
--- /dev/null
+++ b/tools/moztreedocs/docs/rstlint.rst
@@ -0,0 +1,12 @@
+ReStructuredText Linter
+-----------------------
+
+RST isn't the easiest of markup languages, but it's powerful and  what `Sphinx` (the library used to build our docs) uses, so we're stuck with it. But at least we now have a linter which will catch basic problems in `.rst` files early. Be sure to run:
+
+.. code-block:: shell
+
+   mach lint -l rst
+
+to test your outgoing changes before submitting to review.
+
+`More information <RST Linter>`__.
diff --git a/tools/moztreedocs/docs/run-try-job.rst b/tools/moztreedocs/docs/run-try-job.rst
new file mode 100644
index 0000000000..d7fe6b20b8
--- /dev/null
+++ b/tools/moztreedocs/docs/run-try-job.rst
@@ -0,0 +1,27 @@
+Running a try job for Documentation
+-----------------------------------
+
+Documentation has two try jobs associated:
+
+  - ``doc-generate`` - This generates the documentation with the committed changes on the try server and gives the same output as if it has landed on regular integration branch.
+
+   .. code-block:: shell
+
+      mach try fuzzy -q "'doc-generate"
+
+  - ``doc-upload`` - This uploads documentation to `gecko-l1 bucket <http://gecko-docs.mozilla.org-l1.s3.us-west-2.amazonaws.com/index.html>`__ with the committed changes.
+
+   .. code-block:: shell
+
+      mach try fuzzy -q "'doc-upload"
+
+When the documentation is modified, at review phase, reviewbot will automatically generate a temporary documentation with a direct link to the modified pages.
+
+.. important::
+
+   Running try jobs require the user to have try server access.
+
+.. note::
+
+   To learn more about setting up try server or
+   using a different selector head over to :ref:`try server documentation <Pushing to Try>`
diff --git a/tools/moztreedocs/docs/server-synchronization.rst b/tools/moztreedocs/docs/server-synchronization.rst
new file mode 100644
index 0000000000..b47b66503e
--- /dev/null
+++ b/tools/moztreedocs/docs/server-synchronization.rst
@@ -0,0 +1,5 @@
+Server Synchronization
+======================
+
+We now compare all the files that exist on the server against the list of source files in `mozilla-central`.
+Any files on the server that no longer exist in `mozilla-central` are removed.