Mailinglist Archive: yast-devel (91 mails)

< Previous Next >
Re: [yast-devel] Drop *-devel-doc YaST subpackages?
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@xxxxxxxxxxxx
To contact the owner, e-mail: yast-devel+owner@xxxxxxxxxxxx

< Previous Next >
Follow Ups
References