Contribute to Documentation
We use reStructuredText markup language to write the documentation and Sphinx generator to prepare it for the web publication at
https://doc.oroinc.com/. You can find more information about the syntax on the Sphinx website by reading reStructuredText Primer. The most important information is provided in the sections below.
Documentation source files are maintained in the dedicated github repository.
If you are willing to contribute — you are totally welcome. The information below should help you understand the documentation structure and topic organization, useful rst directives and a simple workflow that helps quickly publish a new topic.
Before You Begin
The use of the documentation is subject to the CC-BY-NC-SA 4.0 license.
Before submitting your documentation changes in a pull request, please sign our Contributor License Agreement (CLA). The CLA must be signed for any code or documentation changes to be accepted.
Fork Documentation Project
If you are just making a small change, you can use the Edit this file button directly in the GitHub UI. It will automatically create a fork of our OroPlatform,OroCRM and OroCommerce documentation repository and allow for the creation and submission of a new pull request with your modifications once you are done editing.
For large volume of updates, fixes, and enhancements please use the following process:
Fork a documentation repository.
Clone the forked repository.
Update your local copy of documentation (see Update Documentation for more information on the process and formatting).
Build and test the documentation before submitting a pull request to be sure you haven’t accidentally introduced any layout or formatting issues.
- To build documentation, set up a local build environment by installing Docker and Docker Compose.
- To test your changes before you commit them, run
docker-compose upin the documentation folder.
Check the generated documentation in the
This section is intended to provide you with the basic information of simple text formatting using reStructuredText (reST) markup language. Just enough to update and create new documentation files in Oro documentation.
The most complete information is available in the reStructureText specifications.
Documentation Structure and Topic Organization
The documentation is organized into the tree hierarchy of sections using toctree directive in the index.rst. Sections of the same level reside in the same folder which simplifies navigation and sibling reference.
Sample file structure:
+ user: - index.rst + back-office - topic-1.rst - topic-2.rst - topic-3.rst - index.rst + storefront + img - create_accounts.png - lead_statistics.png + backend: - index.rst + integration - email.rst - LDAP.rst + api -firewall-listeners.rst -request-types.rst - index.rst
Basic Rst Syntax
Use the following markup for the headings to split your topic into sections, subsections, and more granular bits:
Use an underline with =, -, ^, ~, ” to mark up the sections.
Section 1 ========= Section 1.1 ----------- Section 1.1.1 ^^^^^^^^^^^^^ Section 18.104.22.168 ~~~~~~~~~~~~~~~ Paragraph Title """""""""""""""
Preserve the same level of indentation for all lines of the paragraph. More information is available here.
Surround the text with one asterisk (*) for italic text, with two asterisks (**) for bold text, and with double back quotes (``) for
Preformatted text. to use these symbols in the text without affecting the text style, escape them with the backslash (\).
To form a bullet list, start the line with *, +, or - followed by whitespace:
* Item A * Item B - Item C - Item D + Item E + Item F
- Item E
- Item F
To form a numbered list, start the line with Arabic numerals (1,2,3), upper- or lowercase alphabet letters (A,B,C, or a,b,c), upper- or lowercase Roman numerals (I, II, III, or i, ii, iii). You can automatically enumerate the list by starting the lines with a hash sign (#).
Simple numbered list:
1. Item A 2. Item B a) Item C b) Item D i. Item E ii. Item F
- Item E
- Item F
Auto Enumerated List
1. Item A #. Item B a) Item C #) Item D i. Item E #. Item F
- Item E
- Item F
Syntax in Rst: .. attention:: The message text.
The message text.
Syntax in Rst: .. caution:: The caution message.
The caution message.
Syntax in Rst: .. warning:: The warning message.
The warning message.
Syntax in Rst: .. hint:: The hint message.
The hint message.
Syntax in Rst: .. note:: The note message.
The note message.
Syntax in Rst: .. tip:: The tip message.
The tip message.
Syntax in Rst: .. important:: The important message.
The important message.
+------------+------------+-----------+ | Header 1 | Header 2 | Header 3 | +============+============+===========+ | Cell 1.1 | Cell 1.2 | Cell 1.3 | +------------+------------+-----------+ | Cell 2.1 | Cell 2.2 | Cell 2.3 | +------------+------------+-----------+
|Header 1||Header 2||Header 3|
|Cell 1.1||Cell 1.2||Cell 1.3|
|Cell 2.1||Cell 2.2||Cell 2.3|
.. csv-table:: :header: "**OroCRM Field**","**Outlook Field**" :widths: 20, 20 "Subject","Subject" "Priority","Priority" "Due Date","Due Date"
OroCRM Field Outlook Field Subject Subject Priority Priority Due Date Due Date
File Naming Conventions
Please follow the recommendations below when naming the new documentation file:
- Use a topic-based approach (e.g., user-management-permissions-organization.rst).
- Use lowercase letters and Arabic numbers only.
- All source .rst files with more than one word in their name must be separated with a dash (-), not an underscore, to be able to form correct html links on the website (e.g., file-naming-conventions.rst).
- Avoid special symbols (/,$,#, etc).
- Save the file with .rst extension
Add a New Topic
Create topic contents using Restructured Text format and save it following the File Naming Conventions.
All headers in Oro documentation must be capitalized, except for articles (a, the) unless it is the first word in the header and short prepositions (at, or, on, etc.).
Strive for consistency in all headers. Whenever possible, start headers with the same part of speech (nouns, verbs, etc.). This means that, for instance, if 4 of your 5 subheaders begin with a verb, make sure than the fifth header starts with a verb, too.
To link a topic to the global documentation table of contents:
- Identify the best location for the reference to your new topic in the documentation structure.
- Move the newly created file to the selected folder.
- Append the relative document name (without the rst extension) to the toctree definition in the potential parent topic.
For example, when we create a new topic with additional information about price list management in the additional-pricelist-management-info.rst file. To include it into the document structure at the user/back-office/sales/price-lists level, we’ll update the index.rst file in the user/back-office/sales/price-lists directory like in the following example:
.. toctree:: :maxdepth: 1 price-attributes price-list-management
.. toctree:: :maxdepth: 1 price-attributes price-list-management additional-pricelist-management-info
If you are adding more than one topic and your new topics cover the same domain, consider grouping them into a folder.
For better navigation, it is recommended to create a dedicated index.rst file with an overview and references to the topics in the new folder (using .. toctree:: directive).
To attach your newly created group of topics into the general structure, add the reference to the index.rst file to the appropriate location in the documentation hierarchy.
For instance, documentation-structure-and-topic-organization.rst and file-naming-conventions.rst can be saved to the community/contribute folder, can be added to the toctree of the dedicated community/contribute/index.rst.
Finally, community/contribute/index.rst can be added into the community/index.rst toctree to attach the newly created files into the global documentation structure.
Submit Documentation Updates
After documentation review, your changes will be merged to the Oro documentation and will be published on the documentation website.