Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[enh] Script to generate manpages (issues#284) #682

Merged
merged 25 commits into from Jul 2, 2019

Conversation

Projects
None yet
6 participants
@toitoinebzh
Copy link
Contributor

commented Mar 13, 2019

The problem

Yunohost does not provide man pages (YunoHost/issues#284)

Solution

I wrote this script based on help2man. I hope it can help to fix YunoHost/issues#284

To run it
sudo python3 manpages_auto.py

man pages will be created in the output directory

PR Status

this script certainly needs improvements
I do not know where these pages should be stored and where to put this script : HELP WANTED

How to test

to have a look at a man page
man -l output/yunohost

Validation

  • Principle agreement 0/2 :
  • Quick review 0/1 :
  • Simple test 0/1 :
  • Deep review 0/1 :
Show resolved Hide resolved manpages_auto.py Outdated

@alexAubin alexAubin added this to the 3.6.x milestone Apr 1, 2019

@alexAubin alexAubin changed the title Script to generate manpages - Fix #284 [enh] Script to generate manpages (issues#284) Apr 22, 2019

@alexAubin

This comment has been minimized.

Copy link
Member

commented Apr 22, 2019

Sooo I gave this a try and it indeed generates manpages. But it generates one pages per action ... which I don't know what to do with and is clearly too many. I don't think that's the spirit of a manpage where you expect to find all infos on a particular command in just one manpage. Or if it really is big, then maybe split into subcategories like git does with git-add, git-commit, git-...

So in our case, that would be yunohost-user, yunohost-domain, and so on ... But I don't know if those can easily be generated from help2man

@alexAubin alexAubin added work needed and removed tests needed labels Apr 22, 2019

@Psycojoker

This comment has been minimized.

Copy link
Member

commented Apr 28, 2019

I've made some small pythonic fixes without changing the behavior. Feel free to remove some if needed.

@Psycojoker

This comment has been minimized.

Copy link
Member

commented Apr 28, 2019

I get a funny bug when it's run and yunohost isn't installed 😅
2019-04-28-184103_702x413_scrot

@Psycojoker

This comment has been minimized.

Copy link
Member

commented Apr 28, 2019

I think we should probably switch to generate something in the manpages format from the actionsmap.yml file

And apparently manpages are compressed using .gz compression algorithm from what I'm seing.

@Psycojoker

This comment has been minimized.

Copy link
Member

commented Apr 29, 2019

I think we should probably switch to generate something in the manpages format from the actionsmap.yml file

So I end up working on that this night based on this script, I haven't finished yet but I'm pretty advanced in it, I just need to finish the template and I'll have a working script :) (and we'll be able to discuss on how to properly format it)

@Psycojoker Psycojoker referenced this pull request Apr 29, 2019

Merged

[enh] generate manpages from actionsmap #1

0 of 4 tasks complete
@Psycojoker

This comment has been minimized.

Copy link
Member

commented Apr 29, 2019

So I've made an attempt using generation from actionsmap.yml but github sucks at working together on the same PR and I didn't wanted to overwrite everything here so ... I've made a PR on the PR 😐 toitoinebzh#1

Work is not finished as shown in the other PR.

You can see a sample here:

2019-04-29-234231_1107x1001_scrot

@decentral1se

This comment has been minimized.

Copy link
Contributor

commented May 23, 2019

Given that toitoinebzh#1 is now merged, we can close this one off?

@kay0u

This comment has been minimized.

Copy link
Contributor

commented May 23, 2019

I don't think so, look at branches in this PR and in toitoinebzh#1 :-)

@Psycojoker

This comment has been minimized.

Copy link
Member

commented May 26, 2019

Given that toitoinebzh#1 is now merged, we can close this one off?

No, this PR is not finished yed, we still have to modify the debian package to put the generated file in the good directory gziped.

Documentation: https://www.debian.org/doc/debian-policy/ch-docs.html#manual-pages https://www.debian.org/doc/packaging-manuals/fhs/fhs-3.0.html#usrsharemanManualPages

According to the documentation, we need to put this manpage under /usr/share/man/man8/yunohost.8.gz. I've modified the script so we can run:

python generate_manpages.py --gzip --output /usr/share/man/man8/yunohost.8.gz

@alexAubin do you know how we can modify the debian package to execute this command in postinst? According to debian/install we don't copy the doc folder that contains generate_manpages.py

@alexAubin I tried to see how to draw a horizontal line in groff but that documentation page just destroyed my brain and I have to admit defeat :( https://www.gnu.org/software/groff/manual/html_node/Drawing-Requests.html

It also display default value if it exists now:
2019-05-26-032003_404x61_scrot

@Josue-T

This comment has been minimized.

Copy link
Contributor

commented May 27, 2019

@alexAubin do you know how we can modify the debian package to execute this command in postinst? According to debian/install we don't copy the doc folder that contains generate_manpages.py

Is it not here : https://github.com/YunoHost/yunohost/blob/stretch-unstable/debian/postinst#L5-L34

@Psycojoker

This comment has been minimized.

Copy link
Member

commented May 27, 2019

@alexAubin do you know how we can modify the debian package to execute this command in postinst? According to debian/install we don't copy the doc folder that contains generate_manpages.py

Is it not here : https://github.com/YunoHost/yunohost/blob/stretch-unstable/debian/postinst#L5-L34

You only have access to files installed by the install file it seems and we don't install the doc dir :/ (I guess we can but just to launch one script it's not really worth it) or at least I don't see any example or reaching files inside the package in this file.

@alexAubin

This comment has been minimized.

Copy link
Member

commented May 28, 2019

@alexAubin do you know how we can modify the debian package to execute this command in postinst? According to debian/install we don't copy the doc folder that contains generate_manpages.py

@Psycojoker : so the whole thing is probably pretty similar to the thing about bash completion.

It is compiled at build time here :

https://github.com/YunoHost/yunohost/blob/stretch-unstable/debian/rules#L12

which generates the file data/bash-completion.d/yunohost

Then it is copied in /etc/bash_completion.d/ according to https://github.com/YunoHost/yunohost/blob/stretch-unstable/debian/install#L3

So for the present thing, we may :

  • add a line to the rules file to run the script that generate the manpage at build time
  • add a line in the install file to copy path/to/generated/manpage to /where/manpage/lives/
@Psycojoker

This comment has been minimized.

Copy link
Member

commented May 29, 2019

Great, that should be easy to do, thx for your answer :)

@Psycojoker Psycojoker force-pushed the toitoinebzh:manpages branch from 15dfc88 to 47d2383 Jun 2, 2019

@Psycojoker

This comment has been minimized.

Copy link
Member

commented Jun 2, 2019

Rebased.

Also did the modification for the debian package, @alexAubin does it looks good for you and can you test it? I have no idea on how to do that :/

If it works it's ready to merge for me.

@alexAubin

This comment has been minimized.

Copy link
Member

commented Jun 19, 2019

@Psycojoker : Yup that works 👍 (just a smol fix in last commit)

For reference this is how to test debian build/install :

  • I recommend doing the following inside an ynh-dev machine
  • You should install dh-systemd and git-buildpackage (maybe other deps I'm forgetting)
  • Inside the yunohost folder, run dpkg-buildpackage -us -uc to build the .deb (possibly inspect the log to check that everything went as expected)
  • The resulting .deb will be in the parent folder !
  • Then you can run dpkg -i yunohost_x_y_z_all.deb to install the deb on the system
  • Be careful that if you previously ran ynh-dev use-git yunohost this will overwrite stuff in your host files because of the symlinks and stuff !

Should probably copy this piece of doc somewhere, maybe in Vinaigrette's readme...

@alexAubin

This comment has been minimized.

Copy link
Member

commented Jun 19, 2019

(Tho btw the subcategories are still missing ... Idk if that's a showstopper or not, dun' have a strong opinion on that)

@Psycojoker

This comment has been minimized.

Copy link
Member

commented Jun 19, 2019

(Tho btw the subcategories are still missing ... Idk if that's a showstopper or not, dun' have a strong opinion on that)

Ah shit, forgot about it >_>

Will do.

Thx for your help!

@alexAubin alexAubin added work needed and removed tests needed labels Jun 24, 2019

@Psycojoker

This comment has been minimized.

Copy link
Member

commented Jun 29, 2019

Added support for subcategories, I think we can merge now? (once it's tested)

Also: I don't want to touch this horrible template again.

@Psycojoker Psycojoker removed the work needed label Jun 29, 2019

@alexAubin
Copy link
Member

left a comment

LGTM !

Edit: small test and works as expected 👍

@alexAubin alexAubin merged commit d010093 into YunoHost:stretch-unstable Jul 2, 2019

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.