matrix-spec-proposals/specification/targets.yaml

targets:
  main:  # arbitrary name to identify this build target
    files:  # the sort order of files to cat
      - 0-intro.rst
      - 1-client_server_api.rst
      - { 1: 0-events.rst }
      - { 1: 0-event_signing.rst }
      - 2-modules.rst
      - { 1: 0-feature_profiles.rst }
      - { 1: "group:modules" }  # reference a group of files
      - 3-application_service_api.rst
      - 4-server_server_api.rst
      - 5-identity_servers.rst
      - 6-appendices.rst
groups:  # reusable blobs of files when prefixed with 'group:'
  modules:
    - modules/instant_messaging.rst
    - modules/voip_events.rst
    - modules/typing_notifications.rst
    - modules/receipts.rst
    - modules/presence.rst
    - modules/content_repo.rst
    - modules/end_to_end_encryption.rst
    - modules/history_visibility.rst
    - modules/push_overview.rst
      # relative depth
    - { 1: [modules/push_cs_api.rst , modules/push_push_gw_api.rst] }

title_styles: ["=", "-", "~", "+", "^"]

# The templating system doesn't know the right title style to use when generating
# RST. These symbols are 'relative' to say "make a sub-title" (-1), "make a title
# at the same level (0)", or "make a title one above (+1)". The gendoc script
# will inspect this file and replace these relative styles with actual title
# styles. The templating system will also inspect this file to know which symbols
# to inject.
relative_title_styles:
  subtitle: "<"
  sametitle: "/"
  supertitle: ">"
Add a 'targets.yaml' files in /specification We're well beyond the point now where a simple `cat` of .rst files to "build" the spec is practical. We may want to slice and dice the spec in different ways to address various cross-cutting concerns. To this end, there is now a 'targets' file which contains the "build targets" for the spec, which contains the sorting order for the .rst files. For now, we just have a single target: 'main'. 9 years ago			`targets:`
Process and extract targets in gendoc.py 9 years ago			`main: # arbitrary name to identify this build target`
			`files: # the sort order of files to cat`
Rename spec files to not have numbers everywhere; update targets.yaml 9 years ago			`- 0-intro.rst`
Move events sections to CS API 9 years ago			`- 1-client_server_api.rst`
Rename spec files to not have numbers everywhere; update targets.yaml 9 years ago			`- { 1: 0-events.rst }`
			`- { 1: 0-event_signing.rst }`
			`- 2-modules.rst`
Move feature profiles section to modules as a sub-section 9 years ago			`- { 1: 0-feature_profiles.rst }`
Implement relative title styles Templates don't know at what level they will be inserted. Previously, we hard-coded the title style which is not compatible with the build target system. Define a set of styles which will be replaced by the gendoc script when it encounters them: '<' : Make this title a sub-heading '/' : Make this title a heading at the same level '>' : Make this title a super-heading The build target system is now basically complete and functioning. 9 years ago			`- { 1: "group:modules" } # reference a group of files`
Rename spec files to not have numbers everywhere; update targets.yaml 9 years ago			`- 3-application_service_api.rst`
			`- 4-server_server_api.rst`
			`- 5-identity_servers.rst`
			`- 6-appendices.rst`
Process and extract targets in gendoc.py 9 years ago			`groups: # reusable blobs of files when prefixed with 'group:'`
Add a 'targets.yaml' files in /specification We're well beyond the point now where a simple `cat` of .rst files to "build" the spec is practical. We may want to slice and dice the spec in different ways to address various cross-cutting concerns. To this end, there is now a 'targets' file which contains the "build targets" for the spec, which contains the sorting order for the .rst files. For now, we just have a single target: 'main'. 9 years ago			`modules:`
Add instant_messaging module; modify batesian section rules Previously, all `m.room.*` events were wodged into `{{room_events}}` which isn't great when you want to pull specific ones out. Batesian had a 1:1 mapping of `render_foo()` to a section `{{foo}}`, and having to constantly add functions for new types is a PITA. Batesian now supports returning a `dict` instead of a section `string` where the keys are the `{{foo}}` and the value is what will be inserted. Also add conflicting section key checks to avoid multiple definitions of the same `{{foo}}`. Define dicts for event schemata and swagger HTTP APIs. Using this new feature, split out the instant messaging stuff from the events section, and replace `{{room_events}}` with a list of specific events e.g. `{{m_room_member_event}}`. 9 years ago			`- modules/instant_messaging.rst`
Rename spec files to not have numbers everywhere; update targets.yaml 9 years ago			`- modules/voip_events.rst`
			`- modules/typing_notifications.rst`
			`- modules/receipts.rst`
Add presence module; fix relative title bug If a relative title appeared after an HTTP API table, it would insert the wrong level because it thought that part of the table was a title. 9 years ago			`- modules/presence.rst`
Rename spec files to not have numbers everywhere; update targets.yaml 9 years ago			`- modules/content_repo.rst`
			`- modules/end_to_end_encryption.rst`
			`- modules/history_visibility.rst`
			`- modules/push_overview.rst`
Use relative depths for groups instead of absolute ones This means the group can be agnostic to how deeply nested it is, improving reusability of groups. 9 years ago			`# relative depth`
			`- { 1: [modules/push_cs_api.rst , modules/push_push_gw_api.rst] }`
Implement relative title styles Templates don't know at what level they will be inserted. Previously, we hard-coded the title style which is not compatible with the build target system. Define a set of styles which will be replaced by the gendoc script when it encounters them: '<' : Make this title a sub-heading '/' : Make this title a heading at the same level '>' : Make this title a super-heading The build target system is now basically complete and functioning. 9 years ago
			`title_styles: ["=", "-", "~", "+", "^"]`

			`# The templating system doesn't know the right title style to use when generating`
			`# RST. These symbols are 'relative' to say "make a sub-title" (-1), "make a title`
			`# at the same level (0)", or "make a title one above (+1)". The gendoc script`
			`# will inspect this file and replace these relative styles with actual title`
			`# styles. The templating system will also inspect this file to know which symbols`
			`# to inject.`
			`relative_title_styles:`
			`subtitle: "<"`
			`sametitle: "/"`
			`supertitle: ">"`