Documentation: Hidden subpages lose user's location in page tree

[ryyst]

Documentation Bug Report

Actual behavior:

Certain pages in the documentation are in some sort of hidden state, where they are not included in the main navigation / TOC. This includes at least all example code pages and tutorial diff/code pages. For example:

• Start from: https://api.arcade.academy/en/development/example_code/index.html

  • Click: https://api.arcade.academy/en/development/example_code/happy_face.html

• Start from: https://api.arcade.academy/en/development/tutorials/card_game/index.html

  • Click: https://api.arcade.academy/en/development/tutorials/card_game/solitaire_01_diff.html

This causes the new navigation headers to be suddenly closed after user arrives on such a page, somewhat disorienting on the path they took here. This is most noticeable on the flat example page, where one could expect to be just going deeper into the navigation tree via each link click.

Expected behavior:

There should be some indication on where the user arrived from.

But seeing as there are semantically multiple different layers, I'm not sure if the solution here is same for all cases. Rather this is a bigger task of reorganizing the old structure to match new layout in general.

[einarf]

The example pages are not connected to a toctree. I'm not sure how to fix this. There might be some way around it. Also using raw links is not optimal. sticking to labels makes the docs a lot more maintainable. However.. you can't put links using labels in figure for some reason.

[pushfoo]

TL;DR: We might have a shot at fixing this with hidden toctrees.

Certain pages in the documentation are in some sort of hidden state

I don't see a link to solitaire_01_diff.html, but:

The example pages are not connected to a toctree.

To elaborate on this, it's going to be due to one of two things:

1. :orphan: status (the pages you've mentioned)
2. They match exclude_patterns

This has me wondering if we should be using :orphan: so widely. Although it's clear and explicit, it seems to be causing problems.