Project

General

Profile

action #30862

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

Added by jorauch over 3 years ago. Updated over 2 years ago.

Status:
Resolved
Priority:
Normal
Assignee:
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

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

History

#1 Updated by coolo over 3 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

#2 Updated by okurz over 3 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

#3 Updated by okurz over 3 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

#4 Updated by riafarov over 3 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.

#5 Updated by SLindoMansilla over 3 years ago

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

Not enough capacity during sprint 18

#6 Updated by mgriessmeier over 3 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

#7 Updated by okurz over 3 years ago

  • Description updated (diff)
  • Status changed from New to Workable
  • Target version changed from Milestone 16 to Milestone 18

#8 Updated by okurz over 3 years ago

  • Target version changed from Milestone 18 to Milestone 18

#9 Updated by okurz almost 3 years ago

  • Target version changed from Milestone 18 to future

#10 Updated by jorauch almost 3 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

#11 Updated by jorauch almost 3 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

#12 Updated by szarate almost 3 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.

#13 Updated by jorauch almost 3 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

#14 Updated by okurz over 2 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?

#15 Updated by riafarov over 2 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.

#16 Updated by okurz over 2 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.

#17 Updated by jorauch over 2 years ago

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

#18 Updated by okurz over 2 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?

#19 Updated by szarate over 2 years ago

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

#20 Updated by jorauch over 2 years ago

I would like to help you

#21 Updated by jorauch over 2 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

#22 Updated by mgriessmeier over 2 years ago

  • Target version changed from Milestone 23 to Milestone 24

moving to M24

#23 Updated by jorauch over 2 years ago

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

And another go

#24 Updated by jorauch over 2 years ago

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

#25 Updated by jorauch over 2 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

#26 Updated by jorauch over 2 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

#27 Updated by jorauch over 2 years ago

#28 Updated by jorauch over 2 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.

#30 Updated by jorauch over 2 years ago

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

#31 Updated by jorauch over 2 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.
"

#32 Updated by jorauch over 2 years ago

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

#33 Updated by jorauch over 2 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

#34 Updated by SLindoMansilla over 2 years ago

  • Status changed from Feedback to Workable

Feedback provided in the PR. Changes requested.

#35 Updated by jorauch over 2 years ago

  • Status changed from Workable to In Progress

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

#36 Updated by jorauch over 2 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.

Also available in: Atom PDF