Project

General

Profile

Actions
Copy link

action #30862

closed

[functional][u] render documentation of lib/utils

Added by jorauch almost 6 years ago. Updated over 4 years ago.

Status:
Resolved
Priority:
Normal
Assignee:
jorauch
Category:
Enhancement to existing tests
Target version:
SUSE QA - Milestone 24
Start date:
2018-01-26
Due date:
% Done:

0%

Estimated time:
Difficulty:

Description

Acceptance criteria

  • AC1: The documentation of lib/utils rendered in nice HTML is published automatically to a non-personal webpage linked to the github project

Further details

Extend the following Hackweek project to generate automated documentation for lib/utils
https://hackweek.suse.com/16/projects/parser-to-extract-function-names-from-openqa-lib-slash-functions-improve-perl-skills
https://github.com/DrMullings/Scripts-Snippets-Stuff/tree/master/Hackweek

Todo

  • Create webpage from JSON
  • Automatically re-create JSON (and webpage) when utils is changed -> Github File Watcher

Related issues 1 (1 open — 0 closed)

Related to openQA Tests - coordination #50507: [qe-core][functional][saga] document lib/ functionsNew2019-05-08

Actions
Actions
Copy link
 #1

Updated by coolo almost 6 years ago

  • Project changed from openQA Project to openQA Tests
  • Subject changed from [tools] extend lib/utils documentation parser from hackweek project to render documentation of lib/utils

Just call pod2html - if you want to write your own version during hackweek, I leave that to you

Actions
Copy link
 #2

Updated by okurz almost 6 years ago

  • Subject changed from render documentation of lib/utils to [functional]render documentation of lib/utils
  • Category set to Enhancement to existing tests
  • Target version set to Milestone 16
Actions
Copy link
 #3

Updated by okurz over 5 years ago

  • Subject changed from [functional]render documentation of lib/utils to [functional][u] render documentation of lib/utils
  • Due date set to 2018-06-05
Actions
Copy link
 #4

Updated by riafarov over 5 years ago

  • Assignee set to jorauch

Please, make workable. Put acceptance criteria to understand what is expected here.

@okurz: please, review one when have AC.

Actions
Copy link
 #5

Updated by SLindoMansilla over 5 years ago

  • Due date changed from 2018-06-05 to 2018-06-19

Not enough capacity during sprint 18

Actions
Copy link
 #6

Updated by mgriessmeier over 5 years ago

  • Due date deleted (2018-06-19)

riafarov wrote:

Please, make workable. Put acceptance criteria to understand what is expected here.

@okurz: please, review one when have AC.

please do so
dropping for now from Sprint 19

Actions
Copy link
 #7

Updated by okurz over 5 years ago

  • Description updated (diff)
  • Status changed from New to Workable
  • Target version changed from Milestone 16 to Milestone 18
Actions
Copy link
 #8

Updated by okurz over 5 years ago

  • Target version changed from Milestone 18 to Milestone 18
Actions
Copy link
 #9

Updated by okurz about 5 years ago

  • Target version changed from Milestone 18 to future
Actions
Copy link
 #10

Updated by jorauch about 5 years ago

  • Status changed from Workable to In Progress

Since okurz wanted me to ensure this is being worked on I will give this a look

Actions
Copy link
 #11

Updated by jorauch almost 5 years ago

  • Status changed from In Progress to Workable
  • Assignee deleted (jorauch)
  • Target version changed from future to Milestone 22

Assigning a milestone so someone with more web-experience can work on this

Actions
Copy link
 #12

Updated by szarate almost 5 years ago

I'm up for mentoring somebody with this task :), there's already things that allow to publish a webpage from pod to html or other formats :), problem is writing the documentation for lib utils I guess, but that can be a second step.

Actions
Copy link
 #13

Updated by jorauch almost 5 years ago

This ticket is about creating html from the json data my crawler generates from the lib/utils files, in general I would assume that documenting each function with pod would be easier, but until this is done we need to rely on what we have

Actions
Copy link
 #14

Updated by okurz almost 5 years ago

We discussed this as well yesterday in the retrospective. The topic was on the retrospective document for very long so I decided (and asked QSF-u during sprint planning 2019-01-16) to move the notes here:

  • Update documentation
    • openQA, lib/utils functions
    • We could start forcing that all newly introduced methods
    • We need some automated check
    • riafarov will create tickets for related activities

@riafarov have you created tickets already and/or can you link them accordingly?

Actions
Copy link
 #15

Updated by riafarov almost 5 years ago

@okurz: it's a bit naive to assume that I will find comments in the tickets I'm not even watching. I honestly do not remember if I got any tickets created. And I'm not even sure that we need any except this one.

Actions
Copy link
 #16

Updated by okurz almost 5 years ago

hm, don't know. Maybe I mentioned the ticket to you in IRC as we discussed the topic in the retrospective? But I agree that we do not need more tickets. This one suffices.

Actions
Copy link
 #17

Updated by jorauch almost 5 years ago

Haven't we agreed on using POD together with @szarate ?

Actions
Copy link
 #18

Updated by okurz almost 5 years ago

  • Target version changed from Milestone 22 to Milestone 23

Yes, I think so and I also would still prefer that. Did we state anything that is pointing otherwise?

Actions
Copy link
 #19

Updated by szarate almost 5 years ago

Yes, we did agree to do POD. Anybody wants to work together on this by the end of next week? :)

Actions
Copy link
 #20

Updated by jorauch almost 5 years ago

I would like to help you

Actions
Copy link
 #21

Updated by jorauch almost 5 years ago

As discussed with szarate:

  • Mirror generation mechanism from openqa repo
  • use Github Pages on os-autoinst-distri-opensuse

Mechanism for openqa:
https://github.com/os-autoinst/openQA/blob/master/script/generate-documentation

We should use pod2html

Actions
Copy link
 #22

Updated by mgriessmeier over 4 years ago

  • Target version changed from Milestone 23 to Milestone 24

moving to M24

Actions
Copy link
 #23

Updated by jorauch over 4 years ago

  • Status changed from Workable to In Progress
  • Assignee set to jorauch

And another go

Actions
Copy link
 #24

Updated by jorauch over 4 years ago

Set up own testing environment, except authentication everything works fine so far
Not sure how to work around the authentication problem

Actions
Copy link
 #25

Updated by jorauch over 4 years ago

As discussed with szarate we need to use gh-branches for github pages, as pushing to the master is blocked for os-autoinst-distri-opensuse

Actions
Copy link
 #26

Updated by jorauch over 4 years ago

The generation of the documentation now works: https://travis-ci.org/DrMullings/os-autoinst-distri-opensuse

`before_deploy:

  • script/generateUtilsDoc.sh deploy: provider: pages skip_cleanup: true github_token: $GITHUB_TOKEN local-dir: $TRAVIS_BUILD_DIR/docs/ on: branch: master target_branch: gh-pages`

When script/generateDocUtils.sh calls pod2html, this should be fairly simple to extend
Now we need to format the HTML more beautiful and also create a good index.html.
Additionally we need to take care of the configuration of the original os-autoinst-distri-opensuse repo

Actions
Copy link
 #27

Updated by jorauch over 4 years ago

Actions
Copy link
 #28

Updated by jorauch over 4 years ago

  • Status changed from In Progress to Feedback

Created:
https://github.com/os-autoinst/os-autoinst-distri-opensuse/pull/7292

Waiting for merge and first creation of docs.

Actions
Copy link
 #30

Updated by jorauch over 4 years ago

Now waiting for both PRs to be merged, then this can be closed

Actions
Copy link
 #31

Updated by jorauch over 4 years ago

  • Status changed from Feedback to In Progress

PRs are merged, the generation is still not working, trying to fix this

szarate in PR:
"
I guess this had to be something like:

git -C $PWD diff master other-branch -- $file

or even better: use the utils.html file instead so that the already generated one, deploys or not based on wether the file generated is different or not.
"

Actions
Copy link
 #32

Updated by jorauch over 4 years ago

Removing
condition: [ "$(git -C $TRAVIS_BUILD_DIR diff 'lib/utils.pm')" ]
For testing reasons

Actions
Copy link
 #33

Updated by jorauch over 4 years ago

  • Status changed from In Progress to Feedback

Now with working conditions:
https://github.com/os-autoinst/os-autoinst-distri-opensuse/pull/7355
Waiting for merge and then closing it

Actions
Copy link
 #34

Updated by SLindoMansilla over 4 years ago

  • Status changed from Feedback to Workable

Feedback provided in the PR. Changes requested.

Actions
Copy link
 #35

Updated by jorauch over 4 years ago

  • Status changed from Workable to In Progress

Adapted everything except the condition. Maybe we should use the normal diff?

Actions
Copy link
 #36

Updated by jorauch over 4 years ago

  • Status changed from In Progress to Feedback

Szarate, SLindoMansilla and me agreed on splitting out the condition to https://progress.opensuse.org/issues/51272
As the utils.pm is being documented and deployed automatically to gh-pages I think we are done with this ticket.

Actions
Copy link

Also available in: Atom PDF