Restructure ToC

What has changed

The ToC shown on the index page contained links to sections which should not belong on the top level.

I have restructured the ToC so that from the top level we see:

• Installing BuildStream
  • Note: This now includes "BuildStream inside Docker"
• Using BuildStream
  • Note: This now includes "Authoring Projects"
• General Documentation
  • Note: This is a new section which contains "Artifact caches", "Cache Keys" and "Sandboxing"
• Core documentation and references
  • Note: This now contains: "buildstream" under "internals"
• Resources
• Hacking on BuildStream

The ToC tree captions have also been removed as they served no purpose.

Result

What I would like to discuss

1. Thoughts on the "General Documentation" section? Or should we incorporate Artifact Caches, Cache Keys and Sandboxing into the "Core documentation and reference" section?
2. Thoughts on including "Authoring Projects" under the Section "Using BuildStream"?
3. We no longer have section headings on the homepage, thoughts?

added 10 commits

• f073bad8...098ee3cf - 3 commits from branch master
• 2f0ff465 - index.rst: remove captions
• d3fce1a4 - docker.rst: REMOVED and content added to installing
• 6fa25b8d - main_authoring.rst: move to using buildstream
• 2ab49045 - modules.rst: Change location within ToC
• 35cc24a3 - Add a general documentation section
• 2cd2a249 - index.rst: Remove unnecessary toctree blocks
• 2e8f0369 - Consistent titling

Compare with previous version

changed the description

This is wildly different from what we've previously discussed.

I think this is better at a highlevel:

• Installing BuildStream
  • docker and mentions of bst-here is good
• Using BuildStream
  • Getting started guide
  • Examples
  • Commands (explanation of how the different commands work, with the patch we discussed that allows us to add text below every automatically generated section for each command)
• Reference documentation
  • Authoring projects
  • Authoring plugins (core public python API reference is integrated here)
• Resources
• Hacking on BuildStream

I.e., Using BuildStream is the user friendly stuff that doesnt exist yet, the authoring projects is terse reference materials and should not be exposed as easy to follow stuff; although following the exercise in the "Getting started guide" should result in the reader being able to navigate the reference documentation on their own.

Ok, for now I will leave out the Getting Started guide and Examples as I have a template for this in another branch which can be introduced within a following MR?

What about the "buildstream" section? https://buildstream.gitlab.io/buildstream/modules.html

added Documentation label

mentioned in merge request !413 (closed)

What about the "buildstream" section? https://buildstream.gitlab.io/buildstream/modules.html

That is the automatically sphinx generated module index, it belongs with the core python API reference material targeted at plugin authors.

Ok, for now I will leave out the Getting Started guide and Examples as I have a template for this in another branch which can be introduced within a following MR?

Of course, I don't expect that to exist.

mentioned in merge request !414 (closed)

added 12 commits

• 226880ee - 1 commit from branch master
• 515c2668 - index.rst: remove captions
• 127e1c7f - docker.rst: REMOVED and content added to installing
• 4a4e072d - main_authoring.rst: move to using buildstream
• 6ccae25a - modules.rst: Change location within ToC
• 986c6521 - Add a general documentation section
• 5a4c30ac - index.rst: Remove unnecessary toctree blocks
• 022b8683 - Consistent titling
• c9d6c3cf - invoking.rst: renamed to commands.rst (anchors also changed)
• 0447e66e - config.rst: Renamed to user_config.rst and anchors changed
• 4d76a1ae - main_core.rst: Change title and move authoring section to here (from Using)
• 3e1b5bbd - core_framework.rst: New file containing content that was in main_core.rst

Compare with previous version

@tristanvb for your convenience:

added 9 commits

• b1491a75 - main_install.rst: New file with install, docker and artifacts
• 43073960 - main_authoring.rst: move to using buildstream
• 0feedf8c - Add a general documentation section
• 07f5c96b - index.rst: Remove unnecessary toctree blocks
• 42cbdf8e - Consistent titling
• d3ebd873 - invoking.rst: renamed to commands.rst (anchors also changed)
• 80ff66b9 - config.rst: Renamed to user_config.rst and anchors changed
• df3cfc8f - core_framework.rst: New file containing content that was in main_core.rst
• ba96ebeb - main_core.rst: Change title and moved authoring, sandboxing and cachekeys documentation here

Compare with previous version

unmarked as a Work In Progress

added 11 commits

• 880e1913 - 1 commit from branch master
• e355a2aa - index.rst: remove captions
• 2b41b300 - main_install.rst: New file with install, docker and artifacts
• fa5cfbbc - main_authoring.rst: move to using buildstream
• 899de191 - Add a general documentation section
• 178e89ae - index.rst: Remove unnecessary toctree blocks
• c27ddfb8 - Consistent titling
• 5e8669e5 - invoking.rst: renamed to commands.rst (anchors also changed)
• c55cb6a1 - config.rst: Renamed to user_config.rst and anchors changed
• 6f7bcf05 - core_framework.rst: New file containing content that was in main_core.rst
• 5a6459d5 - main_core.rst: Change title and moved authoring, sandboxing and cachekeys documentation here

Compare with previous version

enabled an automatic merge when the pipeline for 5a6459d5 succeeds

added 10 commits

• 221bdb63 - index.rst: remove captions
• 52bc50b3 - main_install.rst: New file with install, docker and artifacts
• bdfa7754 - main_authoring.rst: move to using buildstream
• 9b4f671d - Add a general documentation section
• 013b0c51 - index.rst: Remove unnecessary toctree blocks
• a8013e35 - Consistent titling
• bdbe5c69 - invoking.rst: renamed to commands.rst (anchors also changed)
• 47dffc27 - config.rst: Renamed to user_config.rst and anchors changed
• 73cd728a - core_framework.rst: New file containing content that was in main_core.rst
• f42ccc41 - main_core.rst: Change title and moved authoring, sandboxing and cachekeys documentation here

Compare with previous version

added 5 commits

• 5516014f - Consistent titling
• 59ca5523 - invoking.rst: renamed to commands.rst (anchors also changed)
• 3babb477 - config.rst: Renamed to user_config.rst and anchors changed
• dc90442b - core_framework.rst: New file containing content that was in main_core.rst
• 07812d5c - main_core.rst: Change title and moved authoring, sandboxing and cachekeys documentation here

Compare with previous version

added 13 commits

• 07812d5c...78a86f60 - 3 commits from branch master
• 7fa86ab2 - index.rst: remove captions
• af305359 - main_install.rst: New file with install, docker and artifacts
• 8f2075a1 - main_authoring.rst: move to using buildstream
• 45554f07 - Add a general documentation section
• 5d19d5d8 - index.rst: Remove unnecessary toctree blocks
• 6c833321 - Consistent titling
• 9cd3f332 - invoking.rst: renamed to commands.rst (anchors also changed)
• 72e15aca - config.rst: Renamed to user_config.rst and anchors changed
• 4555eda1 - core_framework.rst: New file containing content that was in main_core.rst
• c6b8fb6f - main_core.rst: Change title and moved authoring, sandboxing and cachekeys documentation here

Compare with previous version

enabled an automatic merge when the pipeline for c6b8fb6f succeeds

added 10 commits

• 51717bcc - index.rst: remove captions
• 011b414a - main_install.rst: New file with install, docker and artifacts
• 9a9f637d - main_authoring.rst: move to using buildstream
• 8c638c46 - Add a general documentation section
• 33f5bb11 - index.rst: Remove unnecessary toctree blocks
• ce09e4ff - Consistent titling
• 8f9f6e90 - invoking.rst: renamed to commands.rst (anchors also changed)
• b8b4159c - config.rst: Renamed to user_config.rst and anchors changed
• 6dca98db - core_framework.rst: New file containing content that was in main_core.rst
• 07af5330 - main_core.rst: Change title and moved authoring, sandboxing and cachekeys documentation here

Compare with previous version