[refactor] Direct reference for existing project docs

[zheliuyu]

Motivation

Related issue: #95

The goal of this refactoring is to reduce the maintenance cost of the documentation.

The specific principle is: if an open-source project provides comprehensive NPU usage documentation, Ascend/docs should directly link to and stay synchronized with this documentation.

Using the verl project as an example, I will explain how to implement this.

Method

Here, the verl project is used for demonstration.

• Use the git submodule to add the subproject to Ascend/docs. The benefits include:
  • Preventing Ascend/docs from becoming bloated by including entire projects.
  • Making updates extremely simple.
• Create an index.rst file in the sources/verl folder to serve as the table of contents for the verl project documentation. This allows users to control the scope of the documentation displayed. In other words, if users do not wish to display all of verl's documentation in Ascend/docs, they can manage this via the index.rst file.
• Add a series of operations to the Makefile:
  • Download verl's submodules before executing make html.
  • Copy verl's documentation files to the build directory. Using the VeOmni project as an example, I have added a warning prompt that triggers if the directory is empty.
  • A crucial step: clean up the submodules.

[zheliuyu]

Local Testing

[zheliuyu]

@fffrog @noemotiovon @lowdy1 Regarding the refactoring discussed in the previous issue, I plan to use this approach. Please review this pr. Thanks.

[noemotiovon]

I think this is a very excellent and forward-looking PR.

In the past, ascend/docs was mainly used and maintained by internal developers. In many cases, developers knew very well how to use the software, but the documentation was not updated based on actual usage, which inevitably led to some degree of lag in the docs. Therefore, I believe that directly referencing and synchronizing documentation from upstream open-source projects, rather than maintaining duplicated content in ascend/docs, is a great approach and can significantly reduce long-term maintenance costs.

From a broader perspective, we also hope to make ascend/docs a unified documentation entry point for Ascend-supported software, making it easier for Ascend users to search, access, and read relevant documentation. Introducing upstream project documentation via submodules avoids bloating the repository while keeping the content aligned with upstream, which fits this goal very well.

At the same time, we strongly welcome and encourage more developers and experienced users from other software projects to contribute usage documentation and help maintain it together. In this way, the documentation can better reflect real-world usage scenarios rather than just describing interfaces or features, which will be highly valuable to the entire Ascend ecosystem.

[noemotiovon]

@hipudding, @fffrog, When time permits, we can discuss this further and explore how ascend/docs should evolve if it is positioned as a unified entry point for users going forward.

[zheliuyu]

Hey @hipudding I noticed you approved the changes. If there's anything else, please feel free to let me know.