发布于 2015-09-14 14:54:07 | 70 次阅读 | 评论: 0 | 来源: 网络整理
This document provides an overview of the global organization of the documentation resource. Refer to the notes below if you are having trouble understanding the reasoning behind a file’s current location, or if you want to add new documentation but aren’t sure how to integrate it into the existing resource.
If you have questions, don’t hesitate to open a ticket in the Documentation Jira Project or contact the documentation team.
The documentation project has two “index files”: /contents.txt and /index.txt. The “contents” file provides the documentation’s tree structure, which Sphinx uses to create the left-pane navigational structure, to power the “Next” and “Previous” page functionality, and to provide all overarching outlines of the resource. The “index” file is not included in the “contents” file (and thus builds will produce a warning here) and is the page that users first land on when visiting the resource.
Having separate “contents” and “index” files provides a bit more flexibility with the organization of the resource while also making it possible to customize the primary user experience.
Additionally, in the top level of the source/ directory, there are a number of “topical” index or outline files. These (like the “index” and “contents” files) use the .. toctree:: directive to provide organization within the documentation. The topical indexes combine to create the index in the contents file.
Because the documentation on any given subject exists in a number of different locations across the resource the “topical” indexes provide the real structure and organization to the resource. This organization makes it possible to provide great flexibility while still maintaining a reasonable organization of files and URLs for the documentation. Consider the following example:
Given that topic such as “replication,” has material regarding the administration of replica sets, as well as reference material, an overview of the functionality, and operational tutorials, it makes more sense to include a few locations for documents, and use the meta documents to provide the topic-level organization.
Current topical indexes include:
Additional topical indexes are forthcoming.
The documentation has a number of top-level folders, that hold all of the content of the resource. Consider the following list and explanations below: