[yast-devel] Drop *-devel-doc YaST subpackages?
Hi all, currently we generate the code documentation using "yardoc" during RPM package build. To save some space in the installed system I have moved the generated documentation to *-devel-doc subpackages in some modules. (In some cases the generated doc was about 2x-3x bigger than the actual code.) But maybe we could go one step further.... What do you think about dropping them completely? Here are some my thoughts: - Does anybody actually use them? IIRC I have never used any devel-doc package, if I need a documentation for a function I usually check the source code or grep the YaST code for example usages. - Do the devel-doc packages still make sense? With YCP the only way was to generate the doc locally, with Ruby and GitHub repositories the generated documentation can be accessed online at RubyDoc.info without need for installing any package. See [1]. - When I want to point someone to a function then I usually post a link to the GitHub sources or to a RubyDoc.info rendered doc (like [2]). - If you really need a local documentation you can always run yardoc manually (via `make doc`/`rake yard`). - Some hand written documentation/screenshots are obsolete anyway, I guess you are not much interested how YaST looked ~15 years ago... :-) [2] IMHO these screenshots and the documentation should be moved to the GitHub wiki. What do you think about it? Affected packages ================= yast2-add-on-devel-doc yast2-boot-server-devel-doc yast2-bootloader-devel-doc yast2-devel-doc yast2-installation-devel-doc yast2-instserver-devel-doc yast2-network-devel-doc yast2-nis-client-devel-doc yast2-nis-server-devel-doc yast2-ntp-client-devel-doc yast2-packager-devel-doc yast2-pkg-bindings-devel-doc (this is for a C++ package, maybe it still makes sense...) yast2-printer-devel-doc yast2-sound-devel-doc yast2-sysconfig-devel-doc yast2-transfer-devel-doc yast2-tune-devel-doc yast2-users-devel-doc [1] http://www.rubydoc.info/find/github?q=yast [2] http://www.rubydoc.info/github/yast/yast-ruby-bindings/master/Yast/Logger [3] https://github.com/yast/yast-nfs-client/blob/master/doc/nfs-client-1-fstab-0... -- Ladislav Slezák Appliance department / YaST Developer Lihovarská 1060/12 190 00 Prague 9 / Czech Republic tel: +420 284 028 960 lslezak@suse.com SUSE -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org To contact the owner, e-mail: yast-devel+owner@opensuse.org
On 5.1.2016 14:10, Ladislav Slezak wrote:
Hi all,
currently we generate the code documentation using "yardoc" during RPM package build. To save some space in the installed system I have moved the generated documentation to *-devel-doc subpackages in some modules. (In some cases the generated doc was about 2x-3x bigger than the actual code.)
But maybe we could go one step further.... What do you think about dropping them completely?
Here are some my thoughts:
- Does anybody actually use them? IIRC I have never used any devel-doc package, if I need a documentation for a function I usually check the source code or grep the YaST code for example usages.
The question is: Who excluding Yast developers use them? The answer is: We do not know, but we should still think about use-cases for the docs first.
- Do the devel-doc packages still make sense? With YCP the only way was to generate the doc locally, with Ruby and GitHub repositories the generated documentation can be accessed online at RubyDoc.info without need for installing any package. See [1].
Although this is true, devel-doc packages are tight to actual packages on the system. Different API, different documentation. IMO many people do not know WHERE to find the documentation and local system is the first place to check.
- When I want to point someone to a function then I usually post a link to the GitHub sources or to a RubyDoc.info rendered doc (like [2]).
Yes, that is good for people that ask for something. But if you have to find it yourself, then it's not so easy.
- If you really need a local documentation you can always run yardoc manually (via `make doc`/`rake yard`).
Which is a fair point - but we should still have this info in /usr/share/doc/packages/ for each package (README.md, DOCUMENTATION.txt ...), moreover with links to the online docs.
- Some hand written documentation/screenshots are obsolete anyway, I guess you are not much interested how YaST looked ~15 years ago... :-) [2]
IMHO these screenshots and the documentation should be moved to the GitHub wiki.
Good idea.
What do you think about it?
Thanks for bringing this up :)
yast2-pkg-bindings-devel-doc (this is for a C++ package, maybe it still makes sense...)
Depends on the use-case. Thx Lukas -- Lukas Ocilka, Systems Management (Yast) Team Leader SLE Department, SUSE Linux -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org To contact the owner, e-mail: yast-devel+owner@opensuse.org
Dne 5.1.2016 v 14:32 Lukas Ocilka napsal(a):
On 5.1.2016 14:10, Ladislav Slezak wrote: [...]
- Does anybody actually use them? IIRC I have never used any devel-doc package, if I need a documentation for a function I usually check the source code or grep the YaST code for example usages.
The question is: Who excluding Yast developers use them? The answer is: We do not know, but we should still think about use-cases for the docs first.
The *-devel-doc packages are designed for developers mainly so there should be just few people who are not YaST core developers and use them... And as the YaST community is tiny I'm almost sure that the set of the users is empty... :-(
Although this is true, devel-doc packages are tight to actual packages on the system. Different API, different documentation.
Rubydoc.info supports also branches, you can generate the doc for any branch (or even a commit), e.g. the SLE12-GA documentation is available here: http://www.rubydoc.info/github/yast/yast-ruby-bindings/SLE-12-GA/index the SLE12-SP1 is here: http://www.rubydoc.info/github/yast/yast-ruby-bindings/SLE-12-SP1/index ...etc
IMO many people do not know WHERE to find the documentation and local system is the first place to check.
Um, in this case it's not that trivial as it might seem. The devel-doc packages are not installed by default, you have to search the packages first. Then install it, list it's content to see what's actually there, start the browser and load the documentation... Even the current situation is not good enough.
- When I want to point someone to a function then I usually post a link to the GitHub sources or to a RubyDoc.info rendered doc (like [2]).
Yes, that is good for people that ask for something. But if you have to find it yourself, then it's not so easy.
We could add links to the main README.md files...
- If you really need a local documentation you can always run yardoc manually (via `make doc`/`rake yard`).
Which is a fair point - but we should still have this info in /usr/share/doc/packages/ for each package (README.md, DOCUMENTATION.txt ...), moreover with links to the online docs.
Yes, as mentioned above.
yast2-pkg-bindings-devel-doc (this is for a C++ package, maybe it still makes sense...)
Depends on the use-case.
The point here is that this is a C++ code. Obviously rubydoc.info cannot process it and publish the generated doc. -- Ladislav Slezák Appliance department / YaST Developer Lihovarská 1060/12 190 00 Prague 9 / Czech Republic tel: +420 284 028 960 lslezak@suse.com SUSE -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org To contact the owner, e-mail: yast-devel+owner@opensuse.org
On Tue, 5 Jan 2016 14:10:59 +0100
Ladislav Slezak
Hi all,
currently we generate the code documentation using "yardoc" during RPM package build. To save some space in the installed system I have moved the generated documentation to *-devel-doc subpackages in some modules. (In some cases the generated doc was about 2x-3x bigger than the actual code.)
But maybe we could go one step further.... What do you think about dropping them completely?
In short, for me it make sense to drop it. As you can have branch related doc, doc is generated on net and if you need it, then it can be generated from source. So unnecessary building for me. Josef -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org To contact the owner, e-mail: yast-devel+owner@opensuse.org
On 05.01.2016 14:10, Ladislav Slezak wrote:
But maybe we could go one step further.... What do you think about dropping them completely?
Very good idea IMHO.
Kind regards
--
Stefan Hundhammer
On 01/05/2016 02:10 PM, Ladislav Slezak wrote:
Hi all,
currently we generate the code documentation using "yardoc" during RPM package build. To save some space in the installed system I have moved the generated documentation to *-devel-doc subpackages in some modules. (In some cases the generated doc was about 2x-3x bigger than the actual code.)
But maybe we could go one step further.... What do you think about dropping them completely?
I'm all for dropping them.
Here are some my thoughts:
[....]
-- Ancor González Sosa YaST Team at SUSE Linux GmbH -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org To contact the owner, e-mail: yast-devel+owner@opensuse.org
On Tue, 2016-01-05 at 14:10 +0100, Ladislav Slezak wrote:
Hi all,
currently we generate the code documentation using "yardoc" during RPM package build. To save some space in the installed system I have moved the generated documentation to *-devel-doc subpackages in some modules. (In some cases the generated doc was about 2x-3x bigger than the actual code.)
But maybe we could go one step further.... What do you think about dropping them completely?
+1 for dropping them. Regards, Imo -- Imobach González Sosa YaST Team at SUSE LINUX GmbH
As nobody objected I have added it into FATE [1] so the product managers can evaluate it and agree with the removal. Thanks for the feedback! Ladislav [1] https://fate.suse.com/320356 -- Best Regards Ladislav Slezák Yast Developer ------------------------------------------------------------------------ SUSE LINUX, s.r.o. e-mail: lslezak@suse.cz Lihovarská 1060/12 tel: +420 284 028 960 190 00 Prague 9 fax: +420 284 028 951 Czech Republic http://www.suse.cz/ -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org To contact the owner, e-mail: yast-devel+owner@opensuse.org
participants (6)
-
Ancor Gonzalez Sosa -
Imobach González Sosa -
Josef Reidinger -
Ladislav Slezak -
Lukas Ocilka -
Stefan Hundhammer