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

move qooxdoo doc to separate repos #9617

Open
hkollmann opened this issue Dec 31, 2018 · 24 comments

Comments

Projects
None yet
6 participants
@hkollmann
Copy link
Member

commented Dec 31, 2018

To discuss and vote:

Should we extract the qooxdoo doc to an seperate repos?
IMHO with this it would be much easier to mantain it.
And we could set up a seperate travis build script for doc only.

@cboulanger

This comment has been minimized.

Copy link
Contributor

commented Dec 31, 2018

This makes sense since running all the tests for a simple documentation change is unnecessary and wasteful.

@derrell

This comment has been minimized.

Copy link
Member

commented Dec 31, 2018

Is this in reference to the manual?

@cboulanger

This comment has been minimized.

Copy link
Contributor

commented Dec 31, 2018

User manual and developer manual, I guess. The new repo should already be on the basis of our new documentation infrastructure (metalsmith? or was that the website? I need an update)

@derrell

This comment has been minimized.

Copy link
Member

commented Dec 31, 2018

Seems to make sense to me. There are no dependencies between it and the code, and I suspect that most people read the documentation online, not from their downloaded qooxdoo library anyway. It makes the normal qooxdoo download smaller, in addition to the travis benefit.

@hkollmann

This comment has been minimized.

Copy link
Member Author

commented Dec 31, 2018

developer nanual has it's own repository: https://github.com/qooxdoo/qx-dev-manual!

@cboulanger

This comment has been minimized.

Copy link
Contributor

commented Dec 31, 2018

I know, but do we still need that if we move the documentation? Maybe it makes sense since it is purely internal and has different rules for PRs.

@hkollmann

This comment has been minimized.

Copy link
Member Author

commented Dec 31, 2018

Moving to it's own is simple. Using Sphinx with reStructuredText is simple too.
Changing the whole doc to another format is much more work.

Website is another task. We have not discussed about this yet. @cajus had some ideas a year ago. But this is'nt discussed further.

@hkollmann

This comment has been minimized.

Copy link
Member Author

commented Dec 31, 2018

is purely internal and has different rules for PRs.

Has it? Where? That should'nt.

We should mark dev docs in qooxdoo as deprecated or remove them.

@cboulanger

This comment has been minimized.

Copy link
Contributor

commented Dec 31, 2018

I wonder: would the old python toolchain (that the current doc system is based on) still work with a separate repo? If yes, fine. If no, why even bother, since we won't be updating the docs as they are? I'd rather use the occasion to change the documentation toolchain and work on the new docs. But I am ready to be convinced that it makes sense to move the old format.

@cboulanger

This comment has been minimized.

Copy link
Contributor

commented Dec 31, 2018

As far as I remember, the main problem was to write a script that converts the old format to whatever we agree on using. Then we'd have to work a bit on tidying up and fixing bugs, but I don't think that is too much if we split the work among us. After that, we could add all the new documentation (compiler etc.).

@cboulanger

This comment has been minimized.

Copy link
Contributor

commented Dec 31, 2018

As to developer manual - I think the rules to change the dev manual are stricter than changing the user manual because they define the rules themselves, a bit like a constitution.

@hkollmann

This comment has been minimized.

Copy link
Member Author

commented Dec 31, 2018

Which do you suggest? md format? I think you move the tec doc once - so the script should not be a problem. More work are the missing features like .. toctree : : ...

      As to developer manual - I think the rules to change the dev manual are stricter than changing the user manual because they define the rules themselves, a bit like a constitution.

Now i see what you mean.

@cboulanger

This comment has been minimized.

Copy link
Contributor

commented Dec 31, 2018

A PR containing only documentation changes needs two assenting votes, whereas a PR containing code changes needs five assenting votes - and the developer manual is treated like code (I think).

@cboulanger

This comment has been minimized.

Copy link
Contributor

commented Dec 31, 2018

I am very much in favor of MarkDown (this could also be published to https://readthedocs.org if we want). And I think we already found a consensus here. To be sure, all dynamic elements need to be generated somehow. So there must be some sort of "compile" step.

@hkollmann

This comment has been minimized.

Copy link
Member Author

commented Dec 31, 2018

Question is why to move. They all support rst as well and this seems the better Format for docs:

http://www.ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/

@derrell

This comment has been minimized.

Copy link
Member

commented Dec 31, 2018

The problem with starting down the path of changing the technology that the docs use, is that it is likely to be a twisty maze of passages all different. There will be some things that don't work properly, and we'll spend quite some time getting the documentation in shape again. My choice would be to put that off to a 6.0.1 release; not try to get it into the upcoming 6.0.0 release.

@hkollmann

This comment has been minimized.

Copy link
Member Author

commented Dec 31, 2018

@derrell : So you suggest to move repos and stay with rst?

@derrell

This comment has been minimized.

Copy link
Member

commented Dec 31, 2018

@hkollmann I don't mind moving the repos, and I think it makes sense to remove stuff that most users don't use from the main qooxdoo repo, but yes, I think that for the moment, we should not change the format of the content as that opens up the possibility of a lot of unanticipated work before the release.

@oetiker

This comment has been minimized.

Copy link
Member

commented Jan 2, 2019

the trouble with splitting the docs from the code is that it could happend that the documentation is not really tied to the release anymore which is a really bad thing ... I happy with splitting it, if we agree on having the same branch structure as the qx repo ... so that it is clear that the documentation is for a particular qx release

@cboulanger

This comment has been minimized.

Copy link
Contributor

commented Jan 2, 2019

The Eric Holscher article was quite convincing... Staying with rst seems to make sense. I need to learn it, I guess.

@johnspackman

This comment has been minimized.

Copy link
Member

commented Jan 3, 2019

I'm not so convinced by Eric Holscher's article because it seems to be saying that the reason for not using Markdown are:
(1) Different versions of "markdown" are incompatible - OK, but who says we need to target some universal/common specification? What's wrong with GitHub Markdown, which is pretty definitive?

(2) Markdown needs to support classes - I can see why this would be useful, but how much of a deal breaker is it for us?

(3) Lack of portability - surely there are portability issues for RST or any other documentation system also? It's only an issue if you are wishing that the term "markdown" means a specific, universal spec, so surely "Github Markdown" is just as portable as (eg) RST

The argument against using RST is that it is a third DSL that we have for documentation - issues and PRs are in GitHub Markdown, code is in JSDoc, and the manual is in RST. Personally, I find RST ugly and awkward to write, and I would much rather see GitHub Markdown for the documentation. (I would also be interested in supporting GitHub Markdown in JSDoc comments, but that's probably another discussion)

As for docs in a separate repo - that's fine by me; perhaps the release/travis script in the main qooxdoo repo can automatically update the version number in the manual repo at the same time? IE enforce that it's always clear which versions relate to each other.

@level420

This comment has been minimized.

Copy link
Member

commented Jan 3, 2019

Currently if someone creates a PR with some new feature in the sdk and also wants to add documentation for that new feature, the PR could contain both the source and documentation change. Having SDK and the docs in separate repos would need 2 separate PRs for that. We need to take care that docs and SDK do not diverge somehow. A sync mechanism is needed, as @johnspackman said, which ensures that the version number gets updated in the docs for the devel docs and for releases. So that's a point against a separate doc repo.

On the other side a separate repo would allow for more agile changes without having to run the full stack of deployment for a simple doc change. That's a favorable point.

So sorry, I'm currently undecided, but willing to follow the majorities decision.

@oetiker

This comment has been minimized.

Copy link
Member

commented Jan 3, 2019

I agree with @johnspackman rst is ugly ... markdown has won ... there is https://commonmark.org/

And I agree with @level420 that it is much easier to require PRs to include doc updates if the documentation is in the same repo ... separating the documentation out will the first step in abandoning it.

@cboulanger

This comment has been minimized.

Copy link
Contributor

commented Jan 3, 2019

I also find rst ugly, but I think that shouldn't influence our decision. What I found convincing in the article is that rst is extensible and, at least to a certain extend, lets us avoid to have to write our own compilation step that inserts into the final markup all the dynamically generated stuff (such as TOCs) which is not supported by GitHub Markdown. If we currently have a working system with that feature and which will be supported for a foreseeable future, it might be wise to stick with it even though we don't like it for aesthetic reasons. But I am also fine with Markdown if we find good tools to achieve the same goal.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.