On 01/07/2015 01:32 PM, Josef Reidinger wrote: > On Wed, 07 Jan 2015 13:25:13 +0100 > Ancor Gonzalez Sosa <[email protected]> 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: [email protected] To contact the owner, e-mail: [email protected]
