Browse files

meta: cleanup to stale meta content

  • Loading branch information...
1 parent 1f390e3 commit d0fe0f434b1dc0962f4d48e61677ff9aa6c16abe @tychoish tychoish committed Nov 5, 2013
Showing with 56 additions and 75 deletions.
  1. +6 −4 README.rst
  2. +4 −0 bin/builddata/intersphinx.yaml
  3. +46 −71 source/meta/organization.txt
@@ -5,16 +5,18 @@ MongoDB Documentation
This repository contains a major revision of the MongoDB
documentation, currently accessible at <>.
You can download and build locally if you already have `Sphinx
-<>`_ installed, with the following command: ::
+<>`_ and other dependencies installed, with
+the following command: ::
git clone git://
cd docs/
+ python
make html
Visit ``docs/mongodb/build/html/index.html`` to view the current state
-of the documentation. You may also wish to install `Pygments
-<>`_ to provide syntax highlighting for code
+of the documentation. See `MongoDB Documentation Buildsystem
+<>`_ for complete
+instructions on building the MongoDB documentation.
To contribute to the documentation please fork this repository on
GitHub and issue a pull request. File issue reports or requests at the
@@ -18,6 +18,10 @@ name: python3
path: python3.inv
+name: sphinx
+path: sphinx.inv
name: django
path: django.inv
@@ -33,74 +33,49 @@ 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 subject-specific landing
-pages indexes combine to create the index in the contents file.
-Topical Indexes and Meta Organization
-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 landing pages include:
-- administration
-- applications
-- crud
-- faq
-- mongo
-- reference
-- replication
-- security
-- sharding
-Additional topical indexes are forthcoming.
-The Top Level Folders
-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:
-- "administration" - contains all of the operational and architectural
- information that systems and database administrators need to know in
- order to run MongoDB. Topics include: monitoring, replica sets, shard
- clusters, deployment architectures, and configuration.
-- "applications" - contains information about application development
- and use. While most documentation regarding application development
- is within the purview of the driver documentation, there are some
- larger topics regarding the use of these features that deserve some
- coverage in this context. Topics include: drivers, schema design,
- optimization, replication, and sharding.
-- "core" - contains overviews and introduction to the core features,
- functionality, and concepts of MongoDB. Topics include: replication,
- sharding, capped collections, journaling/durability, aggregation.
-- "reference" - contains references and indexes of shell functions,
- database commands, status outputs, as well as manual pages for all
- of the programs come with MongoDB (e.g. ``mongostat`` and
- ``mongodump``.)
-- "tutorial" - contains operational guides and tutorials that lead
- users through common tasks (administrative and conceptual) with
- MongoDB. This includes programming patterns and operational guides.
-- "faq" - contains all the frequently asked questions related to
- MongoDB, in a collection of topical files.
+Topical Organization
+The placement of files in the repository depends on the *type* of
+documentation rather than the *topic* of the content. Like the
+difference between ``contents.txt`` and ``index.txt``, by decoupling
+the organization of the files from the organization of the information
+the documentation can be more flexible and can more adequately address
+changes in the product and in users' needs.
+*Files* in the ``source/`` directory represent the tip of a logical
+tree of documents, while *directories* are containers of types of
+content. The ``administration`` and ``applications`` directories,
+however, are legacy artifacts and with a few exceptions contain
+sub-navigation pages.
+With several exceptions in the ``reference/`` directory, there is only
+one level of sub-directories in the ``source/`` directory.
+The organization of the site, like all Sphinx sites derives from the
+:rst:dir:`toctree <sphinx:toctree>` structure. However, in order to annotate
+the table of contents and provide additional flexibility, the MongoDB
+documentation generates :rst:dir:`toctree` structures using
+data from YAML files stored in the ``source/includes/``
+directory. These files start with ``ref-toc`` or ``toc`` and generate
+output in the ``source/includes/toc/`` directory. Briefly this system
+has the following behavior:
+- files that start with ``ref-toc`` refer to the documentation of API
+ objects (i.e. commands, operators and methods,) and the build
+ system generates files that hold :rst:dir:`toctree <sphinx:toctree>`
+ directives as well as files that hold *tables* that list objects and
+ a brief description.
+- files that start with ``toc`` refer to all other documentation and
+ the build system generates files that hold :rst:dir:`toctree
+ <sphinx:toctree>` directives as well as files that hold
+ *definition lists* that contain links to the documents and short
+ descriptions the content.
+- file names that have ``spec`` following ``toc`` or ``ref-toc`` will
+ generate aggregated tables or definition lists and allow ad-hoc
+ combinations of documents for landing pages and quick reference guides.

0 comments on commit d0fe0f4

Please sign in to comment.