Toc

[jburel]

Re-organise the doc in sections

[sbesson]

Wow this is quite a big styling upgrade (using RTD default theme) in addition to a content reorganization - which might address the concerns raised in #16 (comment)

Immediate piece of feedback from my side is that I am not a fan of the intermediate pages like https://ome-contributing--19.org.readthedocs.build/en/19/components-development.html if the only content is a blurb followed by a list of sub-sections. In the top-level page, it also creates an unnecessary nested layer

Unless these section overview pages are deemed to grow, is there any reason not to include the toctree directly under the top-level index.rst?

[jburel]

[joshmoore]

Few points from my side but nothing that necessarily must be handled in this PR:

• I'm certainly used to the RTD styling so no objections.
• I don't particularly need the additional landing pages but no strong feelings. My primary concern would be long-term URL stability.
• In the menu and section headers:
  • I'd suggest prefixing with "OMERO" where appropriate.
  • Also: "BioFormats" needs a hyphen.
• The "documentation" section of "Components development" might belong under "Components release" and if so, "Components release" might just be "Build & Release".
• If so, "Components development" ... I realize this is getting confusing. Here's a proposed TOC:

Getting started (was general)
  - drop docs & data model
...

Oops. Now I see I was too slow. Holding off on any proposals until the dust clears.

[jburel]

@joshmoore Switching to QA so I will not do anything more for now

[sbesson]

Slightly unfortunate that the headings are not also exposed in the left-hand navigation panel (as in https://bio-formats.readthedocs.io/en/latest/users/index.html# for instance). I suspect this comes to the fact they are in the top-level index.rst page and this brings us back to the question of introducing intermediate pages with their own toctrees

[jburel]

@sbesson This is exactly the problem. Either we have intermediate page that show on the left and index or we have the current flat structure

[sbesson]

Fair enough. I think the testing scenarios is a good example of why we might need intermediate pages in the end as the top-level toc tree might become a long flat list of sections otherwise.

As mentioned in #19 (comment), the biggest question is whether we are happy with the proposed structure:

• General/getting started makes sense to me. There should be a clear entry point containing the general information about contributing like using version control, making contributions, CLA...
• Testing is definitely its own section with the number of scenarios
• this leaves the question of whether development & release are two separate sections. I don't have a better proposal to offer at this stage.

[jburel]

I have created 3 parts

• Getting started
• Build and Release
• Testing

The main point is to have the correct links into the intermediate pages so we can add new contribution

Text can be added and improved later on

[sbesson]

At least, I feel comfortable with the division of this documentation into the three sections as proposed in the latest commits.

I think it would be great to get this restructuring reviewed and integrated in some form so that we can work on amending/inserting content.

[jburel]

@joshmoore are you comfortable with the proposed split?

[joshmoore]

Yup. Seconding, @sbesson, this seems like a big improvement. Thanks!