Transfer docs from cylc-flow repo.

[hjoliver]

Close #2

This takes the whole doc directory from cylc/cylc-flow, and relevant bits of setup.py and travis config ... which will probably require some tweaking, or maybe travis is not appropriate here at all given issues related to dependence on other components (below)?

Questions

• our docs are sphinx generated, which suggests that Python setup.py is still appropriate for this repo?

• but how to manage dependence on cylc/cylc-flow ? - needed to generate the command transcripts included in the user guide?

  • normal setup.py dependence requires uploading new versions cylc-flow before generating docs?
  • can we depend on local a local clone for building docs locally?
  • or not specify the dependence here formally, but manually ensure that we run this doc build within an environment that has access to the right cylc-flow version?

[oliver-sanders]

My Answers

our docs are sphinx generated, which suggests that Python setup.py is still appropriate for this repo?

I don't think it matters much how we build the docs. The "standard" way to build Sphinx documentation is via the Makefile which Sphinx auto-generates when you start a project via sphinx-quickstart. Personally I would just make the minor modifications to the makefile as necessary.

but how to manage dependence on cylc/cylc-flow

This repo must have a dependence on Cylc Flow in order to auto-document from docstrings etc.

I think the Cylc documentation should probably be versioned to the Cylc Flow version (see #17). We could just hardcode the Cylc Flow version in the setup.py.

The other alternative would be using the cylc namespace to deliver the "recommended" Cylc bundle (flow, UI-Serv, web-ui, etc) and using this "bundle" as the documentation version...

On a side note we need to get rid of the command which documents the CLI (perhaps with cylc/cylc-flow#2972)

[sadielbartholomew]

I started a PR to fix the build for the docs as on cylc-flow as it currently appears to be broken: cylc/cylc-flow#3179. However, I haven't had time to go back to it since. Is it still worth finishing or do we plan to get this merged soon, which will nullify the core of that PR so I can close it (or recast it, as there are some minor singular line changes in there that should still go be applicable)?

[hjoliver]

@sadielbartholomew - I'd like to get this merged soon. We can tweak doc build and dependency specification later as needed (do you agree @oliver-sanders?) For the moment we can put reminder Issues up on this repo, for stuff to do once the docs have moved here.

[sadielbartholomew]

Sure, thanks @hjoliver. I'll close that PR, in that case, & once the docs are moved over have a look to see what may still be relevant from it & open up a new PR on the docs repo if it seems suitable.

[oliver-sanders]

Seems fine to me, the packaging is broken, have put up a PR to fix:

hjoliver#1

[kinow]

For the build to pass in my local environment, I needed the changes in @oliver-sanders ' pending pull request. But after that the build passed.

@oliver-sanders ' pull request also needed some things amended, including to use the version 8.0a1, which is current development version, and not released to PYPI. That's a bit confusing as the current documentation relies on cylc.flow from 8.0a1, but it uses 8.0a0 as current version, as below.

But we can fix that later with a new alpha release. Left one question about a command imported to this PR. But I don't see anything as a blocker, as this is not intended to be the perfect & final version, but instead a step in migrating the old documentation from cylc-flow to this new repo. So +1 to merge it. Better if we could include @oliver-sanders ' changes, but if not we can re-open his PR directly against this repository after the merge. Either way is fine for me 👍

Thanks!

[hjoliver]

Merged in @oliver-sanders PR.