Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Where should xtriggers be documented? #4

Closed
ColemanTom opened this issue May 7, 2019 · 9 comments
Closed

Where should xtriggers be documented? #4

ColemanTom opened this issue May 7, 2019 · 9 comments
Labels
question Further information is requested
Milestone

Comments

@ColemanTom
Copy link
Collaborator

Whilst looking at #2 I wondered about documentation. That pull request moves some xtriggers from cylc-flow into this repository, but their documentation is still part of the core cylc-flow doco. Should all specific xtrigger doco be pulled into this repository, and cylc-flow doco has a link to this only?

@kinow
Copy link
Member

kinow commented May 7, 2019

Good question! I would say document it here, but maybe users would prefer to have everything in the Cylc User Guide, without having to refer to other documentation?

We will have the same issue with cylc/cylc-ui (née cylc-web), which contains the web application code. Your question is valid for that project too. Should we have its documentation as part of cylc-flow, under that doc folder? cc @cylc/core

@hjoliver
Copy link
Member

hjoliver commented May 7, 2019

I think it is fine to have the general xtrigger documentation in the main repo - i.e. what is an xtrigger, how does it work, and what are the built-in ones (if any? just clock, I think we were discussing...) because the server program has the internal machinery to support xtriggers.

Documentation for how to use specific xtriggers that live in this repo, however, should be in this repo. We'd still have to decide what form that should take though ... maybe text/markdown is sufficient for this?

@kinow
Copy link
Member

kinow commented May 7, 2019

Sounds good to me. We could have some small text/markdown documents, and perhaps even the API generated documentation if useful. +1

@ColemanTom
Copy link
Collaborator Author

Sounds good. I would go with markdown at least initially because it is simple and it should be sufficient. If it grows too large and hard to use, then moving to sphinx could be revisited.

@hjoliver
Copy link
Member

hjoliver commented May 7, 2019

Markdown it is.

@oliver-sanders
Copy link
Member

oliver-sanders commented May 8, 2019

To though in a spanner:

  1. I think auto-generating xtrigger docs from the codebase would be a good way to go.
  2. If using markup try ReStructured Text rather than markdown as this can be integrated into existing Sphinx documentation later. BTW Github can handle ReStructued text as well as markdown.

@hjoliver
Copy link
Member

hjoliver commented May 26, 2019

@ColemanTom to throw in another spanner, we are about to move the User Guide to the new cylc/cylc-doc repo. Have decided to do this because the documentation will have to span multiple separate components of cylc-8.

@oliver-sanders
Copy link
Member

I would say document xtriggers in docstrings in the source code and auto-document them in Sphinx from the new cylc/cylc-doc repo.

BTW moving the repo isn't a barrier to auto-documentation.

@oliver-sanders oliver-sanders added the question Further information is requested label Dec 2, 2019
@oliver-sanders
Copy link
Member

OK, looks like we have a consensus. Closing this question here as "resolved", moving the issue into the Cylc Docs repository:

cylc/cylc-doc#107

@oliver-sanders oliver-sanders added this to the 1.0.0 milestone Dec 2, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
question Further information is requested
Projects
None yet
Development

No branches or pull requests

4 participants