Mailinglist Archive: yast-devel (100 mails)

< Previous Next >
Re: [yast-devel] First steps in the new tutorial
On Wed, 07 Jan 2015 16:02:12 +0100
Ancor Gonzalez Sosa <ancor@xxxxxxx> wrote:

On 01/07/2015 01:32 PM, Josef Reidinger wrote:
On Wed, 07 Jan 2015 13:25:13 +0100
Ancor Gonzalez Sosa <ancor@xxxxxxx> wrote:

On 01/05/2015 10:18 AM, Josef Reidinger wrote:

- I think direct link to Target agent documentation can help,
especially because agent name is system and not target :)...also
something is wrong as link from README in core documentation
lead to 404
http://www.rubydoc.info/github/yast/yast-core/doc/systemagent.md

I have intentionally avoided deep links to documentation when
possible. I prefer to link to rubydoc's landing page for each repo,
because nobody will remember to update the tutorial while
reorganizing the documentation of a repository.

About the name, I used Target because it's always mentioned like
this in [1]. If it's more accurate to say "the System agent,
attached to the .target path". We should then change both rubydoc
and the tutorial to keep everything in sync.
[1]http://www.rubydoc.info/github/yast/yast-core/file/doc/systemagent.md


To be honest this just show how agents are over-engineered :)
I am fine with current state, so we should just fix link in README
to not lead to 404

Easier said than done. :-)

The main problem is that YARD uses a different syntax to link
documentation files than the one used in Github flavored markdown. So
you have to choose: proper links in Github or proper links in
rubydoc.info.

The point here is that yast-core is not really a ruby project and
using YARD (rubydoc.info) for it feels kinda unnatural. I'd say we
already talked about using simply markdown+readthedocs.org for
yast-core documentation. Didn't we?

Sounds reasonable for me.


I'll register the project in readthedocs and remove all current links
to rubydoc.info tomorrow if nobody is against it. Would removing the
.yardopts file have some impact somewhere?

Maybe it is used to genera yast-core-devel-doc, you should better check
it. Otherwise if we plan to stop using rudydoc.info for core, it make
sense to remove this config.

Josef


Cheers.

--
To unsubscribe, e-mail: yast-devel+unsubscribe@xxxxxxxxxxxx
To contact the owner, e-mail: yast-devel+owner@xxxxxxxxxxxx

< Previous Next >