Skip to content
Snippets Groups Projects
Verified Commit 9b78606c authored by Andrei Gherzan's avatar Andrei Gherzan :penguin:
Browse files

readme: Remove documentation related topics 


These topic were replaced by a couple of pharagraphs in the
`contributing` section.

Signed-off-by: Andrei Gherzan's avatarAndrei Gherzan <andrei.gherzan@huawei.com>
parent ccf0c61b
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
contributing/gitlab.rst
+ 22
− 0
View file @ 9b78606c
......@@ -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.
readme/Contributing-to-the-Documentation.rst deleted 100644 → 0
+ 0
− 70
View file @ ccf0c61b
.. 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.)
readme/README.rst
+ 0
− 2
View file @ 9b78606c
......@@ -12,5 +12,3 @@ Contributing Documents
Communication-in-Community
Contribution-Process
Contributing-to-the-Documentation
reStructuredText-Basics
readme/reStructuredText-Basics.rst deleted 100644 → 0
+ 0
− 196
View file @ ccf0c61b
.. 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>`_
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

Copyright © Eclipse Foundation, Inc. All Rights Reserved.     Privacy Policy | Terms of Use | Copyright Agent