Uploader flattens page hierarchy

[JPTeasdale]

If you have a page hierarchy like so:

master_doc.rst
other_doc.rst
other_doc_includes/other_doc_part1.rst
other_doc_includes/other_doc_part2.rst

The uploader does not preserve the page hierarchy as expected and instead creates four documents at the root of the space.

[JPTeasdale]

Hmm I guess this has a problem since you don't know if there is going to be an other_doc_2.rst that also includes other_doc_includes/other_doc_part1.rst

[jdknight]

The only way I can see for one to properly take on some level of page hierarchy support is to rely on Sphinx's toctree markup (please, correct me if I'm wrong). I do not believe this extension should be defining an elaborate hierarchy configuration (i.e. mapping per-page structure) or custom Sphinx markups in order to support some level of page hierarchy (while I don't think this was proposed, I'd rather explicitly rule it out now).

Taking a look at toctree, a capability could be added to that from a master_doc page and a defined toctree (and nested toctree markups), one could provide some level of page hierarchy support. For example, using Kernel documentation as an example, there could be a mapping such as:

• Welcome to The Linux Kernel's documentation ref
  • The Linux kernel user's and administrator's guide
  • Bisecting a bug
  • Kernel Support for miscellaneous (your favourite) Binary Formats v1.1
  • Linux Braille Console
  • Linux allocated devices (4.x+ version)
  • ...
  • Development tools for the kernel ref
  • Coccinelle
  • The Kernel Address Sanitizer (KASAN) ref
  • Using gcov with the Linux kernel
  • ...
  • ...

Some other points to consider:

• Support for page hierarchy should only be enabled if:
  • A configuration option indicates to enable support;
  • A project has a master_doc defined; and,
  • A project's master document defines a toctree.
• It might be ideal to have a configuration option to decide if the entries in a toctree should be siblings or children of the nested page.

[spyoungtech]

Would be nice to see this utilize the confluence 'children display' and/or TOC macros.

[jdknight]

@JPTeasdale, I was finally able to look at your PR (#38; well, a part of it so far). I wanted to make a series of internal changes first with publishing (specifically, with the order of publisher) before trying to take in your changes. I basically copied/modified your contributions (at least for the hierarchy mode support for now) in the following (temporary commits):

• publisher: return rest-made new page ids 0e02fc1078658f9060768f8bd0ce17607c9cc362
• builder: add hierarchy support add6c106b60cb619922db7ff7f872ae00932a733

If you wish to make comments on these changes, please feel free to. Note that these commits are part of a forgotten-autumn branch which will most likely be re-based in the future. Hopefully I'll be able to look at adding the unit test work you've done for this feature as well as looking at the max depth capability as well.

@spyoungtech, good idea! I'll take a look to see how easy this can be done. I'd be nice to (maybe) even apply the maxdepth markup value to the macro's depth attribute.

[jdknight]

@spyoungtech, fyi

• wiki-translator: option to use children display macro in hierarchy mode 97d804a07c5df8627c11424bf2af718b660319eb

[jdknight]

This work should be completed with the changes from PR #70 (specifically, see 9d0dda592a9aabc10634019eb9842eccf705a8ae). The changes are currently available in master and should be made available for next release.

To take advantage of the feature, use the configuration options confluence_max_doc_depth and confluence_page_hierarchy.

@JPTeasdale, thanks for the initial changes/pull requests. Hopefully the feature works as expected. Any issues experienced from using this feature, please make a new issue to cover the specific issue. I'll mark this issue has closed.