On Wed, 07 Jan 2015 16:02:12 +0100 Ancor Gonzalez Sosa <[email protected]> wrote:
> 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? 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: [email protected] To contact the owner, e-mail: [email protected]
