Skip to content

Separate out recipes build from main docs build #916

@sadielbartholomew

Description

@sadielbartholomew

The recipes in the docs are really useful and important, however:

  • they are - naturally given they work with large (often multiple GB in size) datasets - slow to build and prone to errors including ones such as lower-level seg faults which are opaque without resorting to going in with a debugger, and ones relating to issues with the Sphinx build;
  • building them every time we build the main docs is unnecessary since we only need to re-build with new recipes or API changes (though we want to test them all as working each release, that doesn't require building them into the docs again, we can just run the scripts and eventually do image comparison on the plots).

For this reason, it would make life, especially release time, much easier if we can build the recipes separately to the build of the main cf-python docs. We foresee at least two good ways to make the separation. Overall, the ideal solution would allow us to build the recipes separately but have them still seamlessly appearing the main rendered docs site as they are now - which can be done via organising both sets of built HTML and links from one to the other.

At present we are tending towards preferring Option 2 below, since keeping them in the repo keeps the whole of cf-python and its current docs contained in one place with no need to move them and manage another repo. But each has pros and cons.

Options

  1. Move recipes to a new separate repo, with its own documentation infrastructure (in Sphinx, largely identical to the cf-python repo one in config. and theme etc.).
  2. Move recipes to a separate directory within the main cf-python repo with its own docs build, i.e. so a separate make html command applies.
  3. Another option? Happy to hear other suggestions.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationrecipes

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions