On Wed, 07 Jan 2015 16:02:12 +0100 Ancor Gonzalez Sosa <ancor@suse.de> wrote:
On 01/07/2015 01:32 PM, Josef Reidinger wrote:
On Wed, 07 Jan 2015 13:25:13 +0100 Ancor Gonzalez Sosa <ancor@suse.de> 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@opensuse.org To contact the owner, e-mail: yast-devel+owner@opensuse.org