Mailinglist Archive: yast-devel (100 mails)

< Previous Next >
Re: [yast-devel] First steps in the new tutorial
  • From: Ancor Gonzalez Sosa <ancor@xxxxxxx>
  • Date: Wed, 07 Jan 2015 16:02:12 +0100
  • Message-id: <54AD4A74.7020307@suse.de>
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?

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?

Cheers.



--
Ancor González Sosa
YaST Team at SUSE Linux GmbH
--
To unsubscribe, e-mail: yast-devel+unsubscribe@xxxxxxxxxxxx
To contact the owner, e-mail: yast-devel+owner@xxxxxxxxxxxx

< Previous Next >