Project

General

Profile

action #10522

Generate and publish documentation regarding os-autoinst AND openQA properly together

Added by okurz almost 6 years ago. Updated almost 5 years ago.

Status:
Resolved
Priority:
Normal
Assignee:
Category:
Feature requests
Target version:
Start date:
2016-02-01
Due date:
% Done:

50%

Estimated time:
Difficulty:

Description

motivation

see https://github.com/Vogtinator/os-autoinst-distri-opensuse/commit/5ec1630c0692a1a11987ee131c740655888728b1#commitcomment-15800169

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-pages branch 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

Related issues

Related to openQA Project - action #9436: broken link: http://os-autoinst.github.io/openQA/downloads/Resolved2015-11-09

Related to openQA Project - action #10380: Improve documentation on assert_screen as well as extend test developer guidelinesResolved2016-01-22

Related to openQA Project - action #10472: Improve documentation about TIMEOUT_SCALEResolved2016-01-28

History

#1 Updated by okurz almost 6 years ago

  • Related to action #9436: broken link: http://os-autoinst.github.io/openQA/downloads/ added

#2 Updated by rpalethorpe over 5 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?

#3 Updated by okurz over 5 years ago

  • Related to action #10380: Improve documentation on assert_screen as well as extend test developer guidelines added

#4 Updated by okurz over 5 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 :-)

#5 Updated by okurz about 5 years ago

  • Related to action #10472: Improve documentation about TIMEOUT_SCALE added

#6 Updated by okurz about 5 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.

#7 Updated by szarate about 5 years ago

Triggering from ci.opensuse.org SGTM :)

#8 Updated by okurz about 5 years ago

can you tell me what you don't like about the first two proposals?

#9 Updated by okurz about 5 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 5 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.

#11 Updated by szarate about 5 years ago

  • Description updated (diff)

updating the description

#12 Updated by okurz about 5 years ago

  • Status changed from New to In Progress

issues I found:

#13 Updated by okurz about 5 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?

#14 Updated by coolo about 5 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

#15 Updated by okurz@suse.de about 5 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.

#16 Updated by okurz about 5 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.

#17 Updated by coolo about 5 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

#18 Updated by okurz about 5 years ago

  • Category set to Feature requests
  • Assignee set to szarate

szarate, will you take it?

#19 Updated by okurz about 5 years ago

  • Target version set to Milestone 5

#20 Updated by coolo almost 5 years ago

this has been resolved IMO

#21 Updated by okurz almost 5 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.

Also available in: Atom PDF