Split spec into page-per-section

scripts/gendoc.py

@@ -276,6 +276,12 @@ def run_through_template(input, set_verbose):
         raise
 
 
+def get_build_targets(targets_listing):
+    with open(targets_listing, "r") as targ_file:
+        all_targets = yaml.load(targ_file.read())
+    return all_targets["targets"].keys()
+
+
 """
 Extract and resolve groups for the given target in the given targets listing.
 Args:
@@ -386,21 +392,34 @@ def cleanup_env():
     shutil.rmtree("./tmp")
 
 
-def main(target_name, keep_intermediates):
+def main(requested_target_name, keep_intermediates):
     prepare_env()
-    log("Building spec [target=%s]" % target_name)
+    log("Building spec [target=%s]" % requested_target_name)
-    target = get_build_target("../specification/targets.yaml", target_name)
+
-    build_spec(target=target, out_filename="tmp/templated_spec.rst")
+    targets = [requested_target_name]
-    run_through_template("tmp/templated_spec.rst", VERBOSE)
+    if requested_target_name == "all":
-    fix_relative_titles(
+        targets = get_build_targets("../specification/targets.yaml")
-        target=target, filename="tmp/templated_spec.rst",
+
-        out_filename="tmp/full_spec.rst"
+    for target_name in targets:
-    )
+        templated_file = "tmp/templated_%s.rst" % (target_name,)
-    shutil.copy("../supporting-docs/howtos/client-server.rst", "tmp/howto.rst")
+        rst_file = "tmp/spec_%s.rst" % (target_name,)
-    run_through_template("tmp/howto.rst", False)  # too spammy to mark -v on this
+        html_file = "gen/%s.html" % (target_name,)
-    rst2html("tmp/full_spec.rst", "gen/specification.html")
+
-    addAnchors("gen/specification.html")
+        target = get_build_target("../specification/targets.yaml", target_name)
-    rst2html("tmp/howto.rst", "gen/howtos.html")
+        build_spec(target=target, out_filename=templated_file)
+        run_through_template(templated_file, VERBOSE)
+        fix_relative_titles(
+            target=target, filename=templated_file,
+            out_filename=rst_file,
+        )
+        rst2html(rst_file, html_file)
+        addAnchors(html_file)
+
+    if requested_target_name == "all":
+        shutil.copy("../supporting-docs/howtos/client-server.rst", "tmp/howto.rst")
+        run_through_template("tmp/howto.rst", False)  # too spammy to mark -v on this
+        rst2html("tmp/howto.rst", "gen/howtos.html")
+
     if not keep_intermediates:
         cleanup_env()
 
@@ -414,8 +433,9 @@ if __name__ == '__main__':
         help="Do not delete intermediate files. They will be found in tmp/"
     )
     parser.add_argument(
-        "--target", "-t", default="main",
+        "--target", "-t", default="all",
-        help="Specify the build target to build from specification/targets.yaml"
+        help="Specify the build target to build from specification/targets.yaml. " +
+             "The value 'all' will build all of the targets therein."
     )
     parser.add_argument(
         "--verbose", "-v", action="store_true",

specification/intro.rst

@@ -8,6 +8,16 @@ https://github.com/matrix-org/matrix-doc using
 https://github.com/matrix-org/matrix-doc/blob/master/scripts/gendoc.py as of
 revision ``{{git_version}}`` - https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}
 
+APIs
+~~~~
+The following APIs are documented in this specification:
+
+- `Client-Server API <client_server.html>`_ for writing Matrix clients.
+- `Server-Server API <server_server.html>`_ for writing servers which can federate with Matrix.
+- `Application Service API <application_service.html>`_ for writing privileged plugins to servers.
+
+There are also some `appendices <appendices.html>`_.
+
 Changelog
 ~~~~~~~~~
 {{spec_changelog}}

specification/modules/typing_notifications.rst

@@ -5,10 +5,8 @@ Typing Notifications
 
 Users may wish to be informed when another user is typing in a room. This can be
 achieved using typing notifications. These are ephemeral events scoped to a
-``room_id``. This means they do not form part of the `Event Graph`_ but still
+``room_id``. This means they do not form part of the
-have a ``room_id`` key.
+`Event Graph <index.html#event-graphs>`_ but still have a ``room_id`` key.
-
-.. _Event Graph: `sect:event-graph`_
 
 Events
 ------

specification/targets.yaml

@@ -1,16 +1,23 @@
 targets:
-  main:  # arbitrary name to identify this build target
+  index:
     files:  # the sort order of files to cat
       - intro.rst
+  client_server:
+    files:
       - client_server_api.rst
       - { 1: events.rst }
       - { 1: event_signing.rst }
       - modules.rst
       - { 1: feature_profiles.rst }
       - { 1: "group:modules" }  # reference a group of files
+  application_service:
+    files:
       - application_service_api.rst
+  server_server:
+    files:
       - server_server_api.rst
-      - identity_servers.rst
+  appendices:
+    files:
       - appendices.rst
 groups:  # reusable blobs of files when prefixed with 'group:'
   modules: