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)?
Related
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.
I am new to Confluence, and I am playing with it (version 5.10.7).
I am reading the system's code, and I am unable to find out where footer.vm is used. Here is where common-header.vm (another file in Confluence) is used: Inside main.vmd, there is the following line:
#parse("/decorators/includes/common-header.vm")
I am not able to find similar code to use footer.vm.
footer.vm contains following code:
## Page footer for main and admin decorators.
#parse("/decorators/includes/footer-content.vm")
Above code contains the content of the footer.
For example in printable.vmd you can find following which parse the footer file:
#parse ("/decorators/includes/footer.vm")
However, if you want to change the content of the footer you need to change /confluence/decorators/includes/footer-content.vm file.
Also I would recommend you to take a look at this document and ensure that you don't break the EULA.
I'm looking to propose some small tweaks/improvements to my employer's coding standard written in Github markdown (*.md).
I've prepped by reviewing a couple of references this markdown language's formatting conventions.
From my readings I see that I can add URLs in at least two different ways:
Standard HTML:
TEXT
Markdown style links:
[TEXT](LINK_URL)
...and code markdown is written as:
Markdown style:
```LANGUAGE
MY CODE;
```
Implicit code denotation via 4 space indent.
However, I've been unable to find a reference on whether you can include a hyperlink inside a block of code (i.e. to the location of that object's source in your repository).
i.e. I want to do something like:
```javascript
_myQObject: <a title="QML Source for MyQObject" href="URL_TO_SOURCE">MyQObject {}
```
That does not work, however, and I've been unable to find documentation explicitly stating whether this is possible or not.
How can I include a link to a URL within a chunk of formatted Github markdown?
Is this possible?
For reference the basic style guides I've reviewed are:
Github Guides: "Mastering Markdown"
Adam-P's "Markdown Cheatsheet"
How can I include a link to a URL within a chunk of formatted Github markdown?
As far as I know this is not possible.
The original Markdown specification says:
With a code span, ampersands and angle brackets are encoded as HTML entities automatically, which makes it easy to include example HTML tags.
…
Regular Markdown syntax is not processed within code blocks. E.g., asterisks are just literal asterisks within a code block. This means it’s also easy to use Markdown to write about Markdown’s own syntax.
I haven't seen anything in the GitHub Markdown docs to suggest that they have added support for links in code blocks, and nothing I've tried has worked.
I also haven't seen this feature in any other Markdown implementations.
This is a late reply, but for people who come here hoping for a solution, there is a way to add links inside preformatted blocks. If you use an HTML block with <pre> ... </pre> instead of using the code block formatting sequence (i.e., don't use fenced code blocks or indented code blocks), you can then use <a> elements inside the preformatted text block. E.g.
<pre>
myQObject: MyQObject {}
</pre>
You lose the automatic syntax highlighting provided by "proper" code blocks, so there is a tradeoff.
I'm using:
Rails 3.2x
Spree 1.2
Ruby 1.9.3x
I'm trying to edit the title of one of my pages, and I cannot find where it is getting defined. It is showing up in my base ERB file as 'title', but that name is sufficiently generic to make it next to impossible to find where it is defined.
I have prodded everywhere I can think, I've tried searching for "title =", but nothing is working. I tried calling source_location on it, but that appears to only work on methods.
Any tricks for finding where a variable is defined?
I can't think of an elegant way. A dumb-but-probably-effective way would be to dump stack trace in your erb, then see what those locations are doing and if title is defined there. It has to enter somewhere between the start of program and invoking your erb.
When I can't find something, I use grep -ri some_string . at the command-line to recursively search all the content of the directory.
It's also a good tactic to let your editor search all the source code, since the ones worth using have the ability to search through all files in a directory.
it is created from a mixture of product names, a site config, and something else
An alternate trick is to add a HTML-comment section in your ERB file, and put the pertinent information for the components used to create the title into that section. Then, let the pages be generated and look inside the page's content to determine what table and row ID it is, the site_config filename, etc.
You really should be able to figure it out based on the parts that are concatenated to build the title and then search your database or files. That information isn't magically created out of thin air by Rails; Someone had to tell Rails how to define the title. But, people move on, or they don't document correctly, so try the embedded information trick.
I'd like to add a code appendix to my LyX document. There are a few options I already considered, but they all have their problems.
I know a bit about listings, but one problem with those is that, if I copy & paste my code into them, I lose all enters/newlines. Since the code is too large to correct by hand, I was wondering if there is an alternative.
In LyX there is the possibility of inserting child documents, but that seems to be only for .tex files. Would have been ideal if I could just insert my .java file as a child document.
I could print the code to PDF, but it will include margins that mess up the final document, since the PDF is placed on the left margin of the final document and then there is the margin of the PDF. Also, this PDF always contains the entire code and white areas where not the entire page has been filled.
Does anyone have good alternative?
The listings package found here
http://www.ctan.org/tex-archive/macros/latex/contrib/listings/
allows the include of external source code files (look into the reference for \lstinputlisting).
EDIT: here you find some samples how to use it:
http://en.wikibooks.org/wiki/LaTeX/Packages/Listings
If you need to copy-paste code to LyX listing box then use Edit -> Paste Special -> Seletion or Ctrl+Alt+V.
For what it's worth, at least the 2.0 versions of LyX have the ability to include listings as child documents. Insert, File, Child Document, and choose from the dropdown box "Program Listing". This uses the listings package and lets you keep your source in its own file.
If listings doesn't support your language, you can always use something like highlight or source-highlight to generate a latex snippet of syntax-highlighted code that you can add as a child document of type "Input"
Yes, if you copy&paste code into the LyX listings box, you lose all newlines, but you can preprocess your code (insert an extra newline below each line):
$ cat foo.java | sed -e 's/$/\n/' > bar.java
Then you can copy&paste the new file bar.java and everything will be ok.