matrix-spec-proposals/specification/targets.yaml

targets:
  index:
    files:
      - index.rst
  intro:
    files:
      - intro.rst
  client_server:
    files:
      - client_server_api.rst
      - { 1: events.rst }
      - { 1: modules.rst }
      - { 2: feature_profiles.rst }
      - { 2: "group:modules" }  # reference a group of files
    version_label: "%CLIENT_RELEASE_LABEL%"
  application_service:
    files:
      - application_service_api.rst
    version_label: unstable
  server_server:
    files:
      - server_server_api.rst
      - { 1: event_signing.rst }
    version_label: "%SERVER_RELEASE_LABEL%"
  identity_service:
    files:
      - identity_service_api.rst
    version_label: unstable
  push_gateway:
    files:
      - push_gateway.rst
    version_label: unstable
  appendices:
    files:
      - 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.rst
    - modules/third_party_invites.rst
    - modules/search.rst
    - modules/guest_access.rst
    - modules/room_previews.rst
    - modules/tags.rst
    - modules/account_data.rst
    - modules/admin.rst
    - modules/event_context.rst
    - modules/cas_login.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:`
Split spec into page-per-section 9 years ago			`index:`
Add index page 9 years ago			`files:`
			`- index.rst`
			`intro:`
			`files:`
Kill number prefixes for good 9 years ago			`- intro.rst`
Split spec into page-per-section 9 years ago			`client_server:`
			`files:`
Kill number prefixes for good 9 years ago			`- client_server_api.rst`
			`- { 1: events.rst }`
Make section depths consistent 9 years ago			`- { 1: modules.rst }`
			`- { 2: feature_profiles.rst }`
			`- { 2: "group:modules" } # reference a group of files`
Put each bit of spec in its own directory I want to change the URLs for the spec sections on the website from <version>/<section>.html to <section>/<version>.html, to better reflect how we do the versioning. This puts each bit of spec in its own directory, updates the index to point to the right place, and fixes continuserv to deal with directories as well as files. This will probably require fixes to the speculator too, but I'll have to come back to that. 9 years ago			`version_label: "%CLIENT_RELEASE_LABEL%"`
Split spec into page-per-section 9 years ago			`application_service:`
			`files:`
Kill number prefixes for good 9 years ago			`- application_service_api.rst`
Put each bit of spec in its own directory I want to change the URLs for the spec sections on the website from <version>/<section>.html to <section>/<version>.html, to better reflect how we do the versioning. This puts each bit of spec in its own directory, updates the index to point to the right place, and fixes continuserv to deal with directories as well as files. This will probably require fixes to the speculator too, but I'll have to come back to that. 9 years ago			`version_label: unstable`
Split spec into page-per-section 9 years ago			`server_server:`
			`files:`
Kill number prefixes for good 9 years ago			`- server_server_api.rst`
Move event signing to server-server spec It's definitely not a client concern. It isn't really in the right place at the moment, but s-s is very much a work in progress whereas c-s is nearly stable. 9 years ago			`- { 1: event_signing.rst }`
Put each bit of spec in its own directory I want to change the URLs for the spec sections on the website from <version>/<section>.html to <section>/<version>.html, to better reflect how we do the versioning. This puts each bit of spec in its own directory, updates the index to point to the right place, and fixes continuserv to deal with directories as well as files. This will probably require fixes to the speculator too, but I'll have to come back to that. 9 years ago			`version_label: "%SERVER_RELEASE_LABEL%"`
Add initial identity server spec More to come 9 years ago			`identity_service:`
			`files:`
			`- identity_service_api.rst`
Put each bit of spec in its own directory I want to change the URLs for the spec sections on the website from <version>/<section>.html to <section>/<version>.html, to better reflect how we do the versioning. This puts each bit of spec in its own directory, updates the index to point to the right place, and fixes continuserv to deal with directories as well as files. This will probably require fixes to the speculator too, but I'll have to come back to that. 9 years ago			`version_label: unstable`
Change `id` in the push gateway poke to be `event_id` and spec that it's the Matrix event ID of the message. Correct the spec for badge count pushes which omit fields previously described as mandatory. Add more detail about when to use event_id to suppress dupes. Also add the push gateway doc so it's actually included in the spec. 9 years ago			`push_gateway:`
			`files:`
			`- push_gateway.rst`
Put each bit of spec in its own directory I want to change the URLs for the spec sections on the website from <version>/<section>.html to <section>/<version>.html, to better reflect how we do the versioning. This puts each bit of spec in its own directory, updates the index to point to the right place, and fixes continuserv to deal with directories as well as files. This will probably require fixes to the speculator too, but I'll have to come back to that. 9 years ago			`version_label: unstable`
Split spec into page-per-section 9 years ago			`appendices:`
			`files:`
Kill number prefixes for good 9 years ago			`- 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`
Combine push files into one We can fork it out again if it makes sense, but certainly 2/3 of the files were very small and it just adds more complexity when refactoring. 9 years ago			`- modules/push.rst`
Update 3pid invite spec This takes into account: 1) That finding the existing servers of a room is hard 2) Federation 9 years ago			`- modules/third_party_invites.rst`
Add search to targets 9 years ago			`- modules/search.rst`
Specify guest room access This was reviewed as PR #150 and merged from daniel/anonymousaccess 9 years ago			`- modules/guest_access.rst`
Split room previews into a separate module Guest access and room peeking are orthogonal 9 years ago			`- modules/room_previews.rst`
Add the tags module to the specification targets 9 years ago			`- modules/tags.rst`
s/config/account_data/ 9 years ago			`- modules/account_data.rst`
Specify /admin/whois/{userId} 9 years ago			`- modules/admin.rst`
Add event context module 9 years ago			`- modules/event_context.rst`
document CAS login Following the spirit of "document how it is, not how we wish it was", document the CAS login bits. 8 years ago			`- modules/cas_login.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
Add extra new line 9 years ago
Add a new title level to appease gendoc 9 years ago			title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"]
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
			`# 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: ">"`