Generate and publish documentation regarding os-autoinst AND openQA properly together
- 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
#2 Updated by rpalethorpe over 6 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?
#4 Updated by okurz over 6 years ago
- Description updated (diff)
very limited progress. Since creating this issue I created two tests as part of os-autoinst:
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 :-)
#6 Updated by okurz about 6 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
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.
#9 Updated by okurz about 6 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
#10 Updated by szarate about 6 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.
#12 Updated by okurz about 6 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 statement
The 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 like
os-autoinst test API
- http://open.qa/api/testapi should have an introduction section
#13 Updated by okurz about 6 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?
#16 Updated by okurz about 6 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 '18.104.22.168' 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.
#17 Updated by coolo about 6 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