I would like to understand if there is a way for me to include additional documentation with the API docs that get generated by dartdoc.
According to the Package layout conventions there is a getting_started.md file included inside the doc/ directory and is displayed like this ...
enchilada/
...
doc/
api/ ***
getting_started.md
How does that file get incorporated into the docs by dartdoc and where does it show up in the output? I've tried to simply add my own *.md files in the doc/ directory but they don't appear to get used.
I have also read about Categories in the dartdoc documentation which states:
categories: More details for each category/topic. For topics you'd like to document, specify the markdown file with markdown: to use for the category page. Optionally, rename the category from the source code into a display name with 'name:'. If there is no matching category defined in dartdoc_options.yaml, those declared categories in the source code will be invisible.
So I then tried to reference the additional documents in the dartdoc_options.yaml file like this ...
dartdoc:
categories:
"Getting Started":
markdown: doc/getting_started.md
"Search Filters":
markdown: doc/search_filters.md
categoryOrder: ["Getting Started", "Search Filters"]
But that too did not generate any results.
Does anyone know how if it's possible to include additional documentation and if so how to accomplish this?
Dartdoc does not allow arbitrary .md files to be included in API documentation. You can create links to them in the README.md or other documentation, e.g. via GitHub or another web address serving them.
For example, the dartdoc package does this for the 'contributing' documentation, and it shows up in the API docs, here: https://pub.dev/documentation/dartdoc/3.0.0/index.html
Categories will only render if at least one element in the source code is declared as a member of that category, so that feature isn't well suited to this use case.
Related
When examples are included in the generated docs (via #example tag) they are all collected by Doxygen in a list in the generated docs in the section "Examples". In the documentation one can then easily refer to the individual examples via #ref example1.c "example1.c"
This works well.
However, I would like to include a link to the auto-generated section "Examples" (not any of the individual examples) and since its generated I cannot add a section tag that I could later refer to.
Since the generated examples section file is always named examples.html by Doxygen it is of course easy to "cheat" and just insert a markdown link [Examples](examples.html). This, again, works fine for the HTML doc. But, for obvious reason this does not work in the PDF version.
What is the portable way of referring to the "Examples" section that works for all output formats (that I obviously overlook)?
I am trying to add .tex file in the Setting->Grammar of atom/spell-check so that it will check spellings in my document because .tex file is going to be a PDF document, but its not working.
Found out that I was using wrong syntax. Correct scope is text.tex.latex. It was already mentioned in the README file on how to get it. Follow below procedure in Atom Editor.
To enable Spell Check for your current file type: put your cursor in
the file, open the Command Palette (cmd-shift-p), and run the
Editor: Log Cursor Scope command. This will trigger a notification
which will contain a list of scopes. The first scope that's listed is
the one you should add to the list of scopes in the settings for the
Spell Check package. Here are some examples: source.coffee,text.plain, text.html.basic.
It should pop up as below
My Grails (2.4.2) app was created with a bunch of "default/standard" resource bundles:
myapp/
grails-app/
i18n/
messages.properties
messages_fr.properties
I would now like to create my own "custom" resource bundle, that is, define properties in a file outside of these standard messages*.properties files that myapp was created with.
According to the i18n documentation, all bundles need to be prefixed with messages and suffixed .properties. So I added two new props files, one for English and one for French:
myapp/
grails-app/
i18n/
messages.properties
messages_fr.properties
messages_myapp.properties
messages_myapp_fr.properties
For one, I'm not 100% sure I'm interpreting the docs correctly. So if anything about my 2 new props files jumps out at you as being incorrect, please start by letting me know!
Having said that, in all the example from those docs, I don't see where you specify the bundle to use. All of the examples look like this:
<g:message code="fizz.buzz.foo" />
But what if I have a fizz.buzz.foo property defined in both messages_blah.properties and messages_bar.properties?
So I ask: How do I add my own custom resource bundles, and how do I properly refer to them from inside a GSP?
To answer your question you have to understand what Grails (well, Spring really) is doing to accomplish this.
You are on the right path with the multiple files. What you have outlined there matches the documentation and will work.
However, under the covers what is really being done is they are being combined into a single bundle (per language). So there is no need to tell Grails/Spring which bundle to use.
Finally, what happens when the same key is defined multiple times? The first one matched wins. I seem to recall that the order in which the bundles are combined is in file name order, though you should be able to test this pretty quickly.
Hope this helps, and best of luck!
I want to generate documentation for my lua project
but with Ldoc i generate docs for each single lua file and the output file every time overwrite the index.html file .
So my question is how i can generate generate documentation for the whole project with index page that has link to the all pages.
I tried to do that with see tag but i don't know if i can use it to reference to another file not another part in the document
I used this:
ldoc.lua.bat pathtomyproject/filename.lua
The output is the default path myluainstallationpath/doc/index.html.
Try ldoc.lua.bat pathtomyproject instead. This will generate the docs for all the files in pathtomyproject and will generate an index.html that links to each file used in that folder..
I am using the help-balloons plugin
I would like to use it parametrized. I mean, the messages should come from a properties file. In the documentation appears the following:
<g:helpBalloon code="user.name" suffix=".help"/>
In this last example, the code attribute is used to look up the balloon's title within the message bundle and then the suffix is added to the code (producing user.name.help in our example) as the key to be used for looking up the content of the balloon.
My question is:
Where should be located this properties file (message bundle)?
Can I have one message bundle per controller?
Luis
if you looked at the source code for the help balloon tag, it literally uses the grails interationalization code to render the message if given a key. http://fisheye.codehaus.org/browse/grails-plugins/grails-help-balloons/trunk/grails-app/taglib/HelpBalloonTagLib.groovy?r=45243
check out this page http://www.grails.org/doc/1.0.x/guide/10.%20Internationalization.html it tells you where and how to name the file for message bundles.
as for a message bundle per controller, it doesnt seem like you can (at least not apparent from the documentation). but you can hack it by prefixing the message key by the controller name, and thus use the same message bundle file (message.properties_ but still be able to namespace each message.
Where are the Resource bundles:
There is a directory under grails-app called i18n where all the generated resource files are placed, start looking there and see how they are used in the app.
You may be able to just place multiple message files for your controllers in there for organization, just be careful of reusing keys as I'm not sure how that will be handled off hand.
How to access them:
Maybe this will help I hope:
http://www.nabble.com/Organizing-message-bundles-tt16169280.html#a16169280