Documentation Contribution Guide

There are 2 types of documentations in DI-engine:

  1. In-script comments automatically generated by sphinx; this type of documentation is located mostly in the API Doc section.

  2. The documentations besides Type 1, are mostly writtern by hand now.

Any users are welcomed to help make the Docs more comprehensive, specific Doc’s implementation guide are as follows:

  1. All substantial updates (adding new modules, editing the content immensely, etc) should be made by Merge Requests submissions. Developers can update at a new branch, and other users, when contributing to Doc, should fork the project to create a new branch and work on this corresponding branch for implementations. Merge Requests need to be submitted with template and include both clear descriptions on the updated contents and specify a review-assignee;

  2. Developers submitting minor updates (e.g. correct minor typos/errors) can work directly on the corresponding branch(es);

  3. When creating new pages, please update upper-level indices to prevent faulty navigation jumps;

  4. Before submitting a new commit, please preview the documentation on a local repository to ensure both navigation correctness and format correctness. (Corresponding python packages (sphinx etc.) required for preview, the specific dependency list is in ding/setup.py) Procedure as follows:

    • Inside the doc directory, run make html to generate corresponding files; keep in mind that Sphinx builds only updated files. For comprehensive preview, touch each file, delete build, or you can run make clean before running make html;

    • Inside doc/build, use browser to open file index.html (or run open build/html/index.html, note that the path might vary by sphinx action) to enter the main page.

  5. The project requries rst language for the Doc’s implementation. And the contributor can also access Online rst editor to test the related syntax.

  6. Implementation of the Docs can be in Chinese or English. In the premise of clear articulation, use English as much as possible. When choosing to implement in English, please note the following rules:

    • Proper capitalization at the beginning of a sentence;

    • Avoid incorrect usage of , as if using Chinese and use ; or . instead when separating sentences;

    • Please keep in mind the full-width and half-width symbols (especially () and （）); use corresponding symbols for the language used.

  7. When implementing the part of the Docs that is difficult to articulate clearly, we recommend pinning code snippets, graphs, as well as tables to help make comprehensive illustrations (including but not limited to UML graphs, flow-chart, etc.).