Support full TOC from a project and use for Guides project.

[bmunkholm]

Add support for having the entire TOC of a project listed in the root, instead of under a single heading.

This requires coordinated release as 0.41.0 together with crate/cratedb-guide#348.

Preview

See preview in PR-348.

[bmunkholm]

@amotl Highly appreciate any support to properly release this together with the guide PR.

[amotl]

Let's run a preview release in order to supply it to the other patch for testing purposes?

• Move "Getting started" to the root of the TOC cratedb-guide#348?

[amotl]

Thanks for the patch. The surface of this hack does not look too big and too bad, so let's try?

[amotl]

I am not particular happy with "naming things" about "Guides". I am considering it a positively tainted name per Diátaxis now, so let's find a different one.

• Naming things: Per Diátaxis, using "Guides" is not applicable. Use "Handbook" instead. #635

[amotl]

Maybe within that patch, the relocation of docs/index.md to docs/guides/index.md can be handled differently, or omitted at all? I know this solution is hacky as a whole, but maybe we can minimize its impact on this particular detail?

• Move "Getting started" to the root of the TOC cratedb-guide#348 (comment)

[bmunkholm]

Sure we can update the naming to support other new PRs already.

I'm not sure what the alternative would be for relocating the guides index? It seems a natural to me. We could even relocate the guides content to that folder if we want the physical structure to closer represent the TOC. But going forward I envision we will relocate many of the pages under Guides (or whatever it should be called)

[amotl]

I'm not sure what the alternative would be for relocating the guides index? It seems a natural to me.

Understood, thanks.

Sure we can update the naming to support other new PRs already.

Thank you. Let's use handbook, unless you have any strong objections against, to get rid of the guide/guides redundancy and more?

• Move "Getting started" to the root of the TOC cratedb-guide#348 (review)

<a href="/docs/guide/handbook/">Handbook</a>

[amotl]

crate-docs-theme 0.41.0.dev0 has been released so the ingredients of this patch can be tested on downstream projects. It is not too difficult to publish a preview release in case you need it for subsequent iterations.

sink:crate-docs-theme amo$ git diff

diff --git a/src/crate/theme/rtd/__init__.py b/src/crate/theme/rtd/__init__.py
index b045236..5fcfad4 100644
--- a/src/crate/theme/rtd/__init__.py
+++ b/src/crate/theme/rtd/__init__.py
@@ -23,9 +23,10 @@

 import os

-VERSION = (0, 40, 1)
+VERSION = (0, 41, 0)

-__version__ = ".".join(str(v) for v in VERSION)
+#__version__ = ".".join(str(v) for v in VERSION)
+__version__ = "0.41.0.dev0"
 __version_full__ = __version__

make build
make upload

[amotl]

We've built and uploaded .dev1 as designated per updates.

[amotl]

Thanks again. Acknowledging by anticipating this will work out well. Please squash your commits and possibly revert the version bump.

[amotl]

Asking again about my previous request: Maybe this can be adjusted to just point to guide/ again. Does anything speak against it?

<a href="/docs/guide/">Handbook</a>

The relocation caused a problem:

• Documentation feedback on /docs/index.md cratedb-guide#381

[amotl]

You are probably right in your assessment that this won't work as requested. Maybe try again? Otherwise we may find a different solution for mitigating the blank page?

[bmunkholm]

Would that not require that the handbook/index.md file is placed in the root where we currently have the index file that contains the 3 toplevel toc entries? Or am I missing something?

[amotl]

That's probably the dilemma? Or just re-add the main body content there?

[bmunkholm]

Yeah - I was considering the same anyway as it's more clean. It just required a bit of special handling to ensure that the Overview page is selected/bolded initially. Fixed now.

[bmunkholm]

Merging with the build error I expect fixed with a rebuild of the Guide with this PR.