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