action #10522
closedGenerate and publish documentation regarding os-autoinst AND openQA properly together
Added by okurz almost 9 years ago. Updated almost 8 years ago.
50%
Description
motivation¶
ideas¶
- DONE: tests for POD correctness
- DONE: add make targets to check doc
- DONE: generate documentation for testapi with
pod2html testapi.pm > testapi.html - DONE: write a script to checkout
gh-pagesbranch on github and put auto-generated documentation there - DONE: call this as part of travis commands
- include (or reference) the html document instead of the manually written testapi table in openQA documentation
- DONE: automate the documentation generation of openQA docs
- optional: beautify
Updated by okurz almost 9 years ago
- Related to action #9436: broken link: http://os-autoinst.github.io/openQA/downloads/ added
Updated by rpalethorpe over 8 years ago
I think this is quite important. The only separate documentation for os-autoinst should be "this is how you run os-autoinst without OpenQA" and likewise for OpenQA if it is practical to run it with something other than os-autoinst. I think perhaps there has been some progress on this since it was posted though?
Updated by okurz over 8 years ago
- Related to action #10380: Improve documentation on assert_screen as well as extend test developer guidelines added
Updated by okurz over 8 years ago
- Description updated (diff)
very limited progress. Since creating this issue I created two tests as part of os-autoinst:
- t/05-pod.pl
- t/06-pod-coverage.pl
Also, I added targets to the Makefile, e.g. "check-doc", which checks spelling and pod correctness.
I added some ideas to the description how to continue.
Thanks for keeping track of such issues :-)
Updated by okurz about 8 years ago
- Related to action #10472: Improve documentation about TIMEOUT_SCALE added
Updated by okurz about 8 years ago
To publish the documentation the recommended way seems to be to use travis and scripts to publish to the gh-pages branch, e.g. see
- http://stackoverflow.com/questions/23277391/how-to-publish-to-github-pages-from-travis-ci
- https://gist.github.com/domenic/ec8b0fc8ab45f39403dd
- https://github.com/steveklabnik/automatically_update_github_pages_with_travis_example
If concerned about travis pushing something to our repository then one could create another fork and only give push access there.
If you are still not convinced I I suggest to use ci.opensuse.org and trigger the doc building and publishing there.
Updated by okurz about 8 years ago
can you tell me what you don't like about the first two proposals?
Updated by okurz about 8 years ago
github has updated the procedure how to interact with github pages, should make it even easier for us: https://github.com/blog/2289-publishing-with-github-pages-now-as-easy-as-1-2-3
Updated by szarate almost 8 years ago
- % Done changed from 0 to 50
With pr#1106 Most of the ideas proposed by this PR are already covered.
However, it would be great to have also the test library's api (os-autoinst-distri-opensuse for starters) generated within the same fashion, for that we can use Pod::Autopod to generate automated pod for modules existing in the lib/ directory.
Updated by okurz almost 8 years ago
- Status changed from New to In Progress
issues I found:
- http://open.qa/api/testapi/#_x11_start_program shows an example where the POD
I<>tag yields an additional'at the end of the statementThe implementation is distribution specific and not always available.' - the special characters naming table in http://open.qa/api/testapi/#_send_key should be rewrapped but in a way that the source code looks ok, still
- title of http://open.qa/api/testapi is
internalbut should be something likeos-autoinst test API - http://open.qa/api/testapi should have an introduction section
Updated by okurz almost 8 years ago
http://open.qa/api/testapi/#_assert_screen does not seem to be up-to-date after https://github.com/os-autoinst/os-autoinst/pull/690 got merged. when is a regeneration of os-autoinst doc triggered?
Updated by coolo almost 8 years ago
we need to create a push to master of openQA repo. There is hopefully activity on openQA repo that we don't have to create something artificial
Updated by okurz@suse.de almost 8 years ago
My original idea was that os-autoinst publishes his own gh-pages and the
openQA doc page only statically references the os-autoinst gh-pages.
Updated by okurz almost 8 years ago
documentation publishing does not work anymore -> https://travis-ci.org/os-autoinst/openQA/jobs/192442200
The output has been generated at /tmp/openqa-doc-yc3e/output
Cloning into 'out'...
remote: Counting objects: 29731, done.
remote: Compressing objects: 100% (26/26), done.
remote: Total 29731 (delta 5), reused 0 (delta 0), pack-reused 29705
Receiving objects: 100% (29731/29731), 16.51 MiB | 16.35 MiB/s, done.
Resolving deltas: 100% (20092/20092), done.
Branch gh-pages set up to track remote branch gh-pages from origin.
Switched to a new branch 'gh-pages'
mkdir: cannot create directory ‘docs’: File exists
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 49270 100 49270 0 0 613k 0 --:--:-- --:--:-- --:--:-- 616k
Transforming testapi.asciidoc
[gh-pages ba8ed0c2] Update documentation to commit 02196b5
5 files changed, 69219 insertions(+), 7036 deletions(-)
create mode 100644 docs/openqa-documentation-20170116_02196b5.html
create mode 100644 docs/openqa-documentation-20170116_02196b5.pdf
Warning: Permanently added the RSA host key for IP address '192.30.253.112' to the list of known hosts.
Permission denied (publickey).
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.
Updated by coolo almost 8 years ago
https://github.com/os-autoinst/openQA/commit/19e0f8316e176794c3c19900049fb7ab2f504cf0 - I found the bug. But there is a new problem: we need to make sure it only runs once, we now have 4 tests that run in parallel
Updated by okurz almost 8 years ago
- Category set to Feature requests
- Assignee set to szarate
@szarate, will you take it?
Updated by okurz almost 8 years ago
- Status changed from In Progress to Resolved
just regard it as done. The "beautify" part should be part of the boy scout principle we follow.