Standardizing tooling documentation

51 views
Skip to first unread message

Nicklaus McClendon

unread,
Dec 20, 2016, 4:06:41 PM12/20/16
to qubes-devel
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Currently, there are multiple ways manpages are generated and handled
for Qubes tooling, listed below are repositories that likely should
have manpages (primarily command line tools)

qubes-app-linux-img-converter: native in same package, in root of
repository
qubes-app-linux-pdf-converter: none
qubes-app-linux-split-gpg: none
qubes-core-admin: pandoc (rst) and separate docs package, in doc
folder in repo
qubes-core-admin-linux: pandoc (rst) in same package, in doc folder in
repo
qubes-core-qubesdb: none
qubes-mgmt-salt: none

Standardizing manpages and how they should be generated would allow
new users to more easily contribute, new packages to be more easily
on-boarded, and new distros to more easily package Qubes tools. I
propose that each package have a separate docs package, generated from
pandoc, with the source having restructured text in the doc folder in
each repo.

As somewhat an aside, it might also be worth adding a README to each
repo with a brief explanation of what the repository is for, again to
easy the process of on-boarding new user.

kulinacs <nick...@kulinacs.com>
-----BEGIN PGP SIGNATURE-----

iQIzBAEBCAAdFiEEPL+ie5e8l/3OecVUuXLc0JPgMlYFAlhZnMMACgkQuXLc0JPg
MlYUlA/9Fmm3lifJb/ZjgS7IrMP07BmxifDq7uzqgDiyCQnNj8x7IwDM4jsDJhrQ
yhWeGgCZ2YPMD6qDjmnXYSyOuygSoRfRHg32VakwbQlXg6PuBgVAwdEphwdQC6qA
rRgh0vYxSxjZjmd0RMyKwPF9S7aY6NicGMjJIcuDftMteBDgCBtsPTG3Qmc0b1Eg
RRQXFDwOnGqHYTNZi1dPGqX0y1aYLKwN0yLSyc0S/+CKiz7rUVLYhjx0bcE3bs9K
wRxzW4kDQdZUZiTCVhAP3H5rILhVDt4ioe8IUj6HdPErgft+tW7Ro7+IGM/RHi3r
H1LZhV90bJobQ2YM/zixx9pUUOqBwUAHWYd/T1rsmp3BUcAffvjS2XfxgKNFvI30
j0KC/ewhHl5b/5vhbdVlD6FWJiKevQYmYJgcSdtyI2D4j3NwQgrECTzWZxahUWaX
8S+3yTgqdbST6Jo/N/HaN+gvZuSa2AKbp6mR20gbBA0fRI7ReulmV5c0/QtJL4+o
xGBOWz1mVQLlhTWT3RXNAtJGe+9NLFmJ7ASZ6qalNXHVP1T+IpoGTMRD+4yWndGu
rtvJpkxYu+IzyFz2EWOmy1ifPOaF+TipUQkM+piH1f/2Rw2x+LlzJMJttkIoemtI
La3PxSsdxk6c23wXp9lepumbkrf15sdAmzSVNhhSdzqhwiBx4A4=
=4CFO
-----END PGP SIGNATURE-----

Marek Marczykowski-Górecki

unread,
Dec 20, 2016, 4:51:49 PM12/20/16
to Nicklaus McClendon, qubes-devel
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On Tue, Dec 20, 2016 at 04:04:20PM -0500, Nicklaus McClendon wrote:
> Currently, there are multiple ways manpages are generated and handled
> for Qubes tooling, listed below are repositories that likely should
> have manpages (primarily command line tools)
>
> qubes-app-linux-img-converter: native in same package, in root of
> repository
> qubes-app-linux-pdf-converter: none
> qubes-app-linux-split-gpg: none
> qubes-core-admin: pandoc (rst) and separate docs package, in doc
> folder in repo
> qubes-core-admin-linux: pandoc (rst) in same package, in doc folder in
> repo
> qubes-core-qubesdb: none
> qubes-mgmt-salt: none
>
> Standardizing manpages and how they should be generated would allow
> new users to more easily contribute, new packages to be more easily
> on-boarded, and new distros to more easily package Qubes tools. I
> propose that each package have a separate docs package, generated from
> pandoc, with the source having restructured text in the doc folder in
> each repo.

I think separate doc package for man pages was a mistake. But other than
that I agree.

> As somewhat an aside, it might also be worth adding a README to each
> repo with a brief explanation of what the repository is for, again to
> easy the process of on-boarding new user.
>
> kulinacs <nick...@kulinacs.com>
>

- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iQEcBAEBCAAGBQJYWaf3AAoJENuP0xzK19csmhMH+gKQ/c/qeDci3Y8/xapJ5gea
0PaL5aDGbrowD4+i3LUYBr+JRV65CHNNU9QhEMoOobGmJO0G6wST3oE/l8YXiH7O
1ttezROK5Nt7LLzgTpHjtp+yylF40LcCHe/G/70Bv/RGY0HbA2vTY4i3LM5lLc9U
QnVr4PIwg81gfT1wlZCENShdTsc7aN0pRBxiQZvc5WzfDHQax3lzTDE1tfVEM2L9
HaCrSPqPS+oiP45qCZgspOn/IkHm1EACWMIMuvWylVnS6/8fQGasDOYkr4Es+5dd
Etwe9Z+Kbr72Jn0QMDlkZjFOoxMwxbbFd7MDC9QK0HxjtBl27TFyHuP1HwfkMJU=
=+F/+
-----END PGP SIGNATURE-----

Andrew David Wong

unread,
Dec 21, 2016, 3:26:17 AM12/21/16
to Marek Marczykowski-Górecki, Nicklaus McClendon, qubes-devel
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512
Tracking:

https://github.com/QubesOS/qubes-issues/issues/2528

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org
-----BEGIN PGP SIGNATURE-----

iQIcBAEBCgAGBQJYWjyWAAoJENtN07w5UDAwpSoQAMy95D5wAVvD3oPpJgRjqDBi
zsmFRX0YyO26cVJq1XEdl2UpBXkiCC+sJvXHmECYc1nXxVtpUbqbx3RNtpwQBxRh
pl0/BK7BXnqdXqROs8uqGdRHOneJKng0Xwg1x58uxMkp9VUgpsS2trLRfoEguag7
bn8qrm5Pu+HCqI2SUhgST4zCWFB2PSsi6bt7qFLM+1FEOIxqE4QVNMlCApQ1Coi9
okXqJMxw3/L/oxKzcCJtoRaLQwqR7AjDkcsgxznnuRV9oT28nxU8uRXlf5sXwzat
IpUpHjVX3YE2Mh20AKcS79k0he9nkX8OLc5I/6yANb4UKqv5xK5nCrjs0qpvSI3Y
338ZIZwMY/fK5kLH3BBNFgArUf0sl98RhoQQ9vB3Qb7e+VDvGNN0M+wNScBwo/7+
LSxD6bbHvj7BONYNff/KlQ8+vu7PPh9K6287mFdvj3r4LFtf3RsIW7f52HH8HnYs
CEANw9g1gswPMAJcId2iElvwutrXj0UxEwN8I99El/hKbvYN9dRcEUkkg+I4U1r0
YzpKGQInfjgU1ZGk7Wef/o3kDr9N02ihJMZZzM6Kuzx2r5gbyClBc6cTkTJo4T/v
5qG8O6RiGXHt0pUz0Hzz5e2V/oV6K6rsXXHuSQyMdC8vxhVZU+DnkocWfdq1lJkD
75vRGmb2oVzBzE01bQnD
=v4d5
-----END PGP SIGNATURE-----

Wojtek Porczyk

unread,
Dec 21, 2016, 8:40:15 AM12/21/16
to Andrew David Wong, Marek Marczykowski-Górecki, Nicklaus McClendon, qubes-devel
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On Wed, Dec 21, 2016 at 12:25:59AM -0800, Andrew David Wong wrote:
> On 2016-12-20 13:51, Marek Marczykowski-Górecki wrote:
> > On Tue, Dec 20, 2016 at 04:04:20PM -0500, Nicklaus McClendon wrote:
> >> Currently, there are multiple ways manpages are generated and handled
> >> for Qubes tooling, listed below are repositories that likely should
> >> have manpages (primarily command line tools)

(snip)

> >> qubes-core-admin: pandoc (rst) and separate docs package, in doc
> >> folder in repo

(snip)

> >> I propose that each package have a separate docs package, generated from
> >> pandoc, with the source having restructured text in the doc folder in
> >> each repo.
> >
> > I think separate doc package for man pages was a mistake. But other than
> > that I agree.

core-admin core3 generates manpages from RST using sphinx. This will remain
that way, since it makes easier to post them also in HTML using
readthedocs.io:
https://qubes-core-admin.readthedocs.io/en/latest/manpages/index.html

Sphinx is however specific to python. One obviously can write manpages for
other tools using sphinx and rst, but there is no obvious benefit aside from
nice sphinx extensions to RST.


> Tracking:
>
> https://github.com/QubesOS/qubes-issues/issues/2528

Should I also post a comment to this bug?


- --
pozdrawiam / best regards _.-._
Wojtek Porczyk .-^' '^-.
Invisible Things Lab |'-.-^-.-'|
| | | |
I do not fear computers, | '-.-' |
I fear lack of them. '-._ : ,-'
-- Isaac Asimov `^-^-_>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iQIcBAEBCAAGBQJYWoY0AAoJEL9r2TIQOiNRMeoP/AkNUkYTEUXFsZErXtqhAabB
5Y8QIgHb2MJMlZXhHN7XEoQcBAh9j12Co1fkwZPHaaYw66+NPlZPUthZpgd5XgJq
Rsk7RZNpuDPNK5YxCgAX7FDOOEkAJdeDssOh6jOCD7fUGqIYQsOI/fQw9AG8a2IY
Strk7DLWmOD57Zisw/lu3jCj6D8Vpz3KV+loQFrSG1BS4a09I8U1bzhbzwMhjfgH
2qBAmadNd4d2pIjPGbDBIEPVH0bYtpOQoAFQigQhzqfEdIlU6HdGUGOQ7wZF42w1
e9m885XA/mlkqc6Z145SrmJYfYc9/Ds9pA4EVVrZp4tXqlxtvgJ3TRoX5sxJNpLj
7oQjtL5z4cJGSqn7gylpi9I/DNirwR5wUImeaSXSYaJxMR9E7XOAYg9ZY4ZMsspz
3BTN8Foo/WzccQwpurVTUNzKWkiZlmO0xsCZ1bL9jtHBpOC6LaGu0TzwOZhqI77V
HcNxZzVuo92KwbmQti035Njzo1wlqqBDxDpnFq/d8LamOnnGoJIJG2UeXDWKITAI
taeWfjOa3d+i99Ak3hk1H9SqnfWvkvEzGRd3g930KvGwNTW/yvrkh1iINwZCdi+Y
kmr0CZdUTc8Gp9CiQljxnnmjnR9vJcFP1cTzbYeGFiy56jahJLe4bDafKuZ+SkrO
c1qzoPb2/c/i+VMiGHfP
=6pys
-----END PGP SIGNATURE-----

Andrew David Wong

unread,
Dec 21, 2016, 11:29:44 PM12/21/16
to qubes-devel
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

On 2016-12-21 05:40, Wojtek Porczyk wrote:
>> Tracking:
>
>> https://github.com/QubesOS/qubes-issues/issues/2528
>
> Should I also post a comment to this bug?
>

It's not required, but it could help others to find this information
faster in the future, so please feel free to do so.

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org
-----BEGIN PGP SIGNATURE-----

iQIcBAEBCgAGBQJYW1atAAoJENtN07w5UDAwJewQAJs3owOfkG6dFT58mQr5cgwR
xAABERV0ACuCUFsHDoro1WX39mbHqQvNZ7eZ85mXkud5d6IHvDkpaZ/Y99lVJK6x
MVJ3cg5UHh7V/1cv3Xo6ChuFHGNv3Hx6MopPyngeHSOeqUz7C7BdtiX07wto4UX+
giUpaWNsyK7mzfTMG5/UloovTneLvJSnC3afrUrv2VFKLHbiOGth2+dG+mCuvqvi
G2ezNa8QFb3HIDiTaefRWpg7Y4RMZDA6rq9OMIeB3pJYPEPZhkxkRKoqPS2eNshf
y+nFrsG7UvH/fXb9sx2JgEDDb7W8raedjnRg107bT5zmrqr/c3M/hCRTXbD2zZKu
5jqv1j3Oo7xIiCzjRTzxxg5aOPum6Z8YeRIN+Ca9cl2p1yJX31+hTrcRICRPuoyv
UlOkjBPXzH6gtJiXjsnHK012DDHHgEozJzBTnkWe8tB5WJmRr5Mb5S4jMV1hIKlK
0SZZKaPXRvomKvqETi1ORFNf62ixKJfzagHkQqyUk39akl/ncAS/ialIWNHOQ3oL
nnmCoK/L7yk4tMywVP/ng1EiCzBB5c6C+GpXWSv5h4SygyoZGDsnGTQfVkYsRGnh
GMPXnTjvxR/hcjllH5stOGc8BEfPIxy9Lvw0uUXbMYMHgUAYLcvwk8FWgjjstL6b
j10qF2U/wtrYIhYRBgPp
=bTbM
-----END PGP SIGNATURE-----

Reply all
Reply to author
Forward
0 new messages