+1 Seems like a practical solution, especially at this point in time where things like the doc repo structure and the url for the static site have yet to be fully determined. On Jul 7, 2014, at 3:04 PM, Bates, Simon <sba...@ocadu.ca> wrote:
> Hi all, > > We have recently been looking at the documentation for Infusion Framework API > functions. We would like to move the docs from the wiki to comments in the > source code. We will then use Steve's infusion-tags tool to generate HTML > from the source code. > > Last week, I was having a look at the existing Framework API documentation in > the wiki and in some cases we have more information in the wiki than would > comfortably be expressed in source code comments. For > example:http://wiki.fluidproject.org/display/docs/fluid.fetchResources > andhttp://wiki.fluidproject.org/display/docs/fluid.messageResolver each > contain tables and source code blocks. > > When we first discussed this issue at last week's community meeting, we > proposed making infusion-docs Markdown pages for API functions such as those > above; for pages with information that we do not want to move to the source > code. We proposed inserting hyperlinks into the source code comments of the > form "For more information see <a href="...">...</a>" which would point to > the corresponding doc page. > > My thinking is now that putting hyperlinks directly into the source code is a > little too fragile. There would be ways to deal with this fragility in the > future, but initially, I would like to propose that we instead point the user > to a doc page simply in text: "For more information see the ... page in the > Infusion documentation". > > In the future, I can see us potentially augmenting the infusion-docs tool to > process an extra configuration table which specifies which API functions have > doc pages. The tool would then insert appropriate links into the generated > HTML, rather than the URLs being hardcoded into the source code. > > Does directing the user with text and without an automated hyperlink seem > like a reasonable initial solution? Please let me know. > > Thanks, > Simon > > _______________________________________________________ > fluid-work mailing list - fluid-work@fluidproject.org > To unsubscribe, change settings or access archives, > see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work
_______________________________________________________ fluid-work mailing list - fluid-work@fluidproject.org To unsubscribe, change settings or access archives, see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work
