diff --git a/building-project-documentation.rst b/building-project-documentation.rst new file mode 100644 index 0000000000000000000000000000000000000000..1cd75c8cd45c08d270d0f4ca1c683303fb6243e8 --- /dev/null +++ b/building-project-documentation.rst @@ -0,0 +1,58 @@ +.. SPDX-FileCopyrightText: Huawei Inc. +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. include:: definitions.rst + +Building |main_project_name| documentation +########################################## + +This topic outlines the standard way of generating the |main_project_name| +project documentation locally using the source files available in the +`git.ostc-eu.org <https://git.ostc-eu.org/OSTC/OHOS/docs>`__ repository which +aggregates documentation from multiple other components. + +Overview +******** + +The |main_project_name| documentation is written in reStructuredText markup +language (``.rst`` file extension) with Sphinx extensions to generate a +structured stand-alone website. + +To generate the HTML documentation locally, Sphinx must be installed on your +local system. Also, to build the documentation using the provided ``Makefile``, +make must also be available on your host. + +For more details on Sphinx installation, refer `Sphinx Getting Started <https://www.sphinx-doc.org/en/master/usage/quickstart.html>`__. + +Building the documentation +************************** + +To generate a local copy of |main_project_name| documentation, perform the +following steps: + +1. Create a local workspace and clone the |main_project_name| project files to + your local, refer to :ref:`setting up a repo workspace <RepoWorkspace>` + section for more information. +2. To generate output as HTML, run the following command: + +.. code-block:: console + + $ make + +The HTML output is built and can be viewed in your browser from the *<docs +repository>/build/index.html* path. + +.. note:: + + * All the local Sphinx warnings and errors generated during the build + process must be fixed and validated. + * To validate the changes, execute ``make clean && make`` command to + generate a clean HTML output. + +Reference +********* + +`<https://www.sphinx-doc.org/en/master/contents.html>`_ + +`<https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_ diff --git a/index.rst b/index.rst index a3f1e1125c1ff69352bf107ce820cec480db30d2..068e5234d73a4e17b4269d31ea1891ef5f4d1533 100644 --- a/index.rst +++ b/index.rst @@ -28,6 +28,7 @@ daily life. contributing/index ci/index repos/index + building-project-documentation ip-policy/index code-of-conduct community-chat-platform