diff --git a/contributing/gitlab.rst b/contributing/gitlab.rst index 65585fc558805b5eee0d66bcc9b447f632841093..290f4cc3f7eabc4c5d9e4ac760bb7fd4c388bbd3 100644 --- a/contributing/gitlab.rst +++ b/contributing/gitlab.rst @@ -20,3 +20,25 @@ that once you have an account, you can fork any repository, create a branch with proposed changes and raise a merge request against the forked repository. More generic information you can find on the Gitlab's documentation as part of `"Merge requests workflow" <https://docs.gitlab.com/ee/development/contributing/merge_request_workflow.html>`_. + +Contributions to Documentation +****************************** + +In |main_project_name|, the documentation usually stays with the respective code +repositories. This means that contributing to documentation is not in any way +different than contributing to code. The processes, contribution guidelines are +to remain the same. The only difference is that documentation files are to be +released under ``Creative Commons License version 4.0``. + +Documentation that doesn't link directly to one specific repository, is +available in the `docs repository <https://git.ostc-eu.org/OSTC/OHOS/docs>`_. + +In terms of file format, the project unifies its documentation as +``ReStructuredText`` files. A RestructuredText primer is available as part of +the Read The Docs `documentation <https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html>`_. + +As a rule of thumb, anything that ends up compiled in the project documentation +is to maintain the RestructuredText file format. Text files that are not meant to be compiled +as part of the project's documentation can be written in `Markdown <https://daringfireball.net/projects/markdown/>`_. +For example, a repository ``README`` file can be written in Markdown as it +doesn't end up compiled in the project-wide documentation. diff --git a/readme/Contributing-to-the-Documentation.rst b/readme/Contributing-to-the-Documentation.rst deleted file mode 100644 index 16b035012dbbf06316a8474fae2494ebe9e6ec19..0000000000000000000000000000000000000000 --- a/readme/Contributing-to-the-Documentation.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. SPDX-FileCopyrightText: Huawei Inc. -.. -.. SPDX-License-Identifier: CC-BY-4.0 - -.. _document-contribution: - -.. include:: ../definitions.rst - -Documentation Contribution -########################## - -You are welcome to make contributions to documentation. You can offer your feedback and contributions in various ways. You can evaluate available documents, make simple modifications, provide feedback on document quality, and contribute your original content. - -Excellent contributors will be awarded and the contributions will be publicized in the developer community. - -* :ref:`contribution-method` -* :ref:`reStructuredText Basics <restructured-text>` - -Content copyright -***************** -The content and pictures submitted by users must be original content and must not infringe others' intellectual property rights. - -|main_project_name| has the right to modify the content that is adopted according to the community regulations and specifications. - -License -******* -`Creative Commons License version 4.0 <https://creativecommons.org/licenses/by/4.0/legalcode>`_ - -.. _contribution-method: - -Contribution method -******************* - -Simple modification -=================== -You can perform the following steps to modify a document or supplement some content: - -#. In the upper right corner of the document page, click **Edit** to go to the source file page in the Gitlab project. -#. On the page of the source file in **.rst** format, click **Edit** to modify or supplement the file. -#. After the modification, click **Preview** to confirm the modification result. -#. Enter your comments and supplementary information in the **Extended Information** text box and click **Submit**. - - The document team will review your modifications and update the file content accordingly. - You will be appreciated for your support and contributions for the |main_project_name| documentation. - -For more information on contributing to |main_project_name|, see :ref:`Contribution Process <contribution-process>`. - -Feedback on documentation -========================= -High-quality feedback helps us continuously improve the documents. The more detailed information you provide, the more helpful it is for us to solve problems. - -On the Gitlab page, click the **Issue** tab. On the displayed page, click **New issue**. Then enter the issue title and issue details. -Click **New** to submit the issue. The document team will confirm the issue. - -.. note:: - * Provide a clear description of the issue, including the missing, outdated, incorrect, or to-be-improved content. - * Explain the impact of this issue on users. - * Limit the scope of the given issue to a specific task. If many fields are involved, break the issue down into smaller ones. - For example,"Documents need to be optimized" is a broad issue, whereas "XX development guide lacks introduction to step XXX" is specific - and operable. - * Search the list of existing issues to see if any related or similar issues have been submitted. - * If an issue is associated with another issue or a pull request, you can use its full URL or PR number with the number sign (#) to - reference it. - -Content creation -================ -You are encouraged to summarize experience and create technical content during learning and development to help more developers quickly get started. Tutorials and FAQs are recommended. The following templates are for reference: - -* Tutorial: Title (Task Name) -* Title (Briefly Describe the Key Information of the Issue.) diff --git a/readme/README.rst b/readme/README.rst index 078ef05f25ae485e7bcdf44c795da8bb202db629..9f918e3d6c7a82ecb6935e7c4fbcc527e55deeca 100644 --- a/readme/README.rst +++ b/readme/README.rst @@ -12,5 +12,3 @@ Contributing Documents Communication-in-Community Contribution-Process - Contributing-to-the-Documentation - reStructuredText-Basics diff --git a/readme/reStructuredText-Basics.rst b/readme/reStructuredText-Basics.rst deleted file mode 100644 index 150dabd225e27616e04992bfaaefee7443c175f6..0000000000000000000000000000000000000000 --- a/readme/reStructuredText-Basics.rst +++ /dev/null @@ -1,196 +0,0 @@ -.. SPDX-FileCopyrightText: Huawei Inc. -.. -.. SPDX-License-Identifier: CC-BY-4.0 - -.. _restructured-text: - -.. include:: ../definitions.rst - -Documentation using Sphinx -########################## - -This topic aims to describe a standard way of documenting using reStructuredText with Sphinx and publising to ReadTheDocs. reStructuredText is plaintext that uses simple and intuitive constructs to indicate the structure of a document. - -Sphinx installation -******************* -Sphinx is written in Python and supports Python 3.6+. It builds upon the shoulders of many third-party libraries such as Docutils and Jinja, which are installed when Sphinx is installed. For more details on Sphinx Installation, see https://www.sphinx-doc.org/en/master/usage/installation.html. - -Setting up the documentation sources -==================================== - -The root directory of a Sphinx collection of plain-text document sources is called the source directory. This directory also contains the Sphinx configuration file conf.py, where you can configure all aspects of how Sphinx reads your sources and builds your documentation. - -Sphinx comes with a script called sphinx-quickstart that sets up a source directory and creates a default conf.py with the most useful configuration values from a few questions it asks you. To use this, enter the below command in windows prompt to initialise Sphinx project: - -.. code-block:: console - - sphinx-quickstart - -The below quickstart screen appears as shown below: - -**Figure 1 quickstart utility** - -.. figure:: images/quick-start.PNG - -For more information on Sphinx Quickstart, refer https://sphinx-rtd-tutorial.readthedocs.io/en/latest/sphinx-quickstart.html. - -Defining Document Structure -=========================== - -sphinx-quickstart creates a source directory with **conf.py** and a **master document**, and **index.rst**. The main function of the master document is to serve as a welcome page, and to contain the root of the “table of contents tree†(or toctree). **index.rst** is the main things that Sphinx adds to reStructuredText, a way to connect multiple files to a single hierarchy of documents. - -The toctree directive initially is empty as below: - -.. code:: cpp - - .. toctree:: - :maxdepth: 2 - -You add documents listing them in the content of the directive: - -.. code:: cpp - - .. toctree:: - :maxdepth: 2 - - usage/installation - usage/quickstart - -For Populating our documentation, refer https://sphinx-rtd-tutorial.readthedocs.io/en/latest/build-the-docs.html - -Building our Documentation -========================== - -In Sphinx source files, you can use most features of standard reStructuredText. Some of the basic syntax with examples are explained below: - -Paragraph ---------- - -Paragraphs in reStructuredText are blocks of text separated by at least one blank line. All lines in the paragraph must be indented by the same amount: - -**Syntax** - -.. code-block:: console - - * Use one asterisk (*text*) for italic - * Use two asterisks (**text**) for bold - * Use two backticks (``text``) for code sample - -**Output** - -* Use one asterisk (*text*) for italic -* Use two asterisks (**text**) for bold -* Use two backticks (``text``) for code sample - -Headers -------- - -Headers are demarcated by non-alphanumeric characters like dashes, equal signs, or tildes. Use the same character for headers at the same level. The following creates a header: - -- Document title (h1) use **“#â€** for the underline character - -- First section heading level (h2) use **“*â€** - -- Second section heading level (h3) use **“=â€** - -- Third section heading level (h4) use **“-“** - -**Syntax** - -.. code-block:: console - - Heading one - ########### - Heading two - *********** - Heading three - ============= - Heading four - ------------ - -Bullet Lists ------------- -A text block which begins with a **"*"**, **"+"**, **"-"**, **"•"**, **"‣"**, or **"âƒ"**, followed by whitespace, is a bullet list item (a.k.a. "unordered" list item). List item bodies must be left-aligned and indented relative to the bullet; the text immediately after the bullet determines the indentation. - -**Syntax** - -.. code-block:: console - - * This is a bulleted list. - * It has two items, the second item uses two lines - -**Output** - -* This is a bulleted list. -* It has two items, the second item uses two lines. - -Numbered Lists --------------- -An numerator consists of a sequence member and formatting, followed by whitespace. - -**Syntax** - -.. code-block:: console - - #. This is a bulleted list. - #. It has two items, the second item uses two lines - -**Output** - -1. This is a bulleted list. -2. It has two items, the second item uses two lines. - -Figure ------- -Images are a common use for substitution reference. - -**Syntax** - -.. code-block:: console - - .. figure:: <folderpath/filename> - -Tables -====== - -The "list-table" directive is used to create a table from data in a uniform two-level bullet list. "Uniform" means that each sublist (second-level list) must contain the same number of list items: - -**Syntax** - -.. code-block:: console - - ===== ===== ======= - A B A and B - ===== ===== ======= - False False False - True False False - False True False - True True True - ===== ===== ======= - -**Output** - -===== ===== ======= -A B A and B -===== ===== ======= -False False False -True False False -False True False -True True True -===== ===== ======= - - -Publishing the documentation to ReadTheDocs -******************************************* - -Once documentation is built, procees to upload it to read the docs. To pubish the document to ReadTheDocs, see https://sphinx-rtd-tutorial.readthedocs.io/en/latest/read-the-docs.html. - - -Reference -********* - -`<https://www.sphinx-doc.org/en/master/contents.html>`_ - -`<https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_ - -`<https://docs.zephyrproject.org/latest/guides/documentation/index.html>`_