I've been using AsciiDocs to write all my documentation, and i was wondering if i could take it a step further and generate the html from my source code, like how JavaDoc does with Java source code.
For example, JavaDoc allows the developer to leave in-line comments that will later be used to generate the html documentation. Is this possible with AsciiDocs? Or do I just need to write the documentation separately?
Javadoc is somewhat modular and extensible: you can use a custom formatting syntax in javadoc comments if you generate the documentation with a custom "doclet".
For AsciiDoc, such a doclet already exists: https://github.com/asciidoctor/asciidoclet
Javadoc is specific to Java, if you use other programming languages there are other tools. Doxygen was created specially for C and C++ but it supports several programming languages and comment styles. For Python, there is pydoc. Whether there's a way to make these support AsciiDoc syntax, you'll have to investigate on your own.
Related
According to the Concordion Getting Started guide:
Note: Since v2.0, Concordion also supports Markdown specifications,
which are easier to read and write than HTML. However, HTML provides a
richer language, so may be preferred for complex scenarios.
What can you do in HTML in a Concordion SPE that you cannot do in Markdown?
From the Concordion syntax point of view, one is handling unusual sentence structures. Another is using the Collapse Extension with Markdown.
Note that we are in the process of updating our Markdown parser from Pegdown to Flexmark, which may open up opportunities to do a bit more in Markdown.
I am creating a MATLAB package using object-oriented programming. I have documented my classes according to a tutorial from MathWorks website. This standard of documentation, however, only works for doc and help commands, but not when I use publish. For example, properties, which have their description written in front of their declaration, don't have said declaration exported to HTML. There is no list of properties or methods at the beginning of the file, so that users can quickly skip to those. Lastly, documentation has to be read directly from the comments in the code, instead of being parsed to HTML.
When I try to add some HTML documentation inside my classes to publish them, the code also appears on doc and help, which is an undesired behavior. Is there a way to create class documentation so that properties and methods can be published to the Web? I've had experience with doc generators like Sphinx (Python) and Doxygen (many languages), in which the descriptions of classes, methods and properties are parsed to HTML so they can be published in places like Read the Docs or GitHub Pages so I am curious to know if MATLAB has something like that.
You can give a try to MTOC++ which uses Doxygen, therefore produces the standard Doxygen HTML documentation.
I have used it already to generate source code documentation for Matlab project containing standard Matlab functions, old class definitions with # notation and classes defined by classdef mixed, and it worked after some tailoring.
This somewhat larger project allows to create documentation for MatLab
files and classes (including packages) using a doxygen filter named
mtoc++. Moreover, a tool/class named MatlabDocMaker allows to create
the documentation from within MatLab. For Windows, Mac and Unix!
You can find it also on Mathworks File Exchange and you can find the documentation here.
One widely-used way to provide HTML documentation for MATLAB functions/class is the M2HTML project. It will automatically generate HTML documentation complete with dependency graphs, source code, and syntax highlighting.
What syntax highlighting is used on GitHub (for HTML, CSS, JavaScript, C#) when viewing source code-file and is it available for the public to use?
It works on the page and it works when embedding on a page (from a Gist), like this:
<script src="https://gist.github.com/1009439.js"></script>
But can I just include their JavaScript-library and let it highlight my code?
Github uses pygments to highlight syntax. Pygments is running on the server, instead of a pure Javascript client solution. If you're looking for a Javascript solution check out this review of the various options.
According to this help page, GitHub currently highlights syntax with the open-source Linguist library for Ruby. Linguist highlights each language using the tmLanguage files linked in vendor/grammars.
Since Linguist is written in Ruby, it can only be used on the server. If you want a client-side JavaScript library that you can just include on a page, you will have to find a different library.
According to this: http://www.infoq.com/news/2008/03/github-git-repository-hosting
they are using Python Pygments
Chris Wanstrath shared some
information about the inner workings
of GitHub with InfoQ:
GitHub is mostly implemented in Rails.
The post-commit integration mini-apps
we're working on are all written in
Merb, we use the Python Pygments for
syntax highlighting, and we use Ara T.
Howard's Bj plus some Ruby scripts for
our queueing system. And, of course,
we use the Ruby Grit library to
interface with Git.
I believe they use their albino gem. It is a Ruby wrapper for the pygments syntax highlighter.
Here is an article of a comparison I read recently on javascript based syntax highlighters (if that is what you need): http://softwaremaniacs.org/blog/2011/05/22/highlighters-comparison/
As others have said previously, GitHub uses Pygments. You can achieve the same effect by using it together with pygments-style-github.
I am designing a class library designed to solve a wide scope of problems. One thing about this library is that it will be usable by several different languages and environments natively. For example, there will be a C++ version written entirely in C++, a .NET version written in C# and a Java version written in Java, without any dependencies on each other... as opposed to writing the core library in C++ and simply providing .NET and Java bindings to it.
The library in each of its different forms sets out to solve a different but sometimes very similar set of problems. For example, there might be many classes whose members will be functionally identical in each language, and there will also be many classes that will be present in only one or two language-versions of the library, but not the others. Take a class or struct representing a program's version number. .NET already has such as class (System.Version) so I would not include it in my .NET version but the C++ and Java libraries would provide one.
The problem I am facing is that for classes which will exist in most or all versions of the library, the documentation will remain relatively the same (obviously). The brief text for both the C++ and Java version for a Version struct would be something like "Represents a software version number in the form major.minor.build.revision"... as would the detailed class description, and all the members' documentation, etc. As you know, .NET, Java and C++ all have their own documentation syntax. Is there any way I can attempt to consolidate documentation in a language-neutral way (WITHOUT writing the documentation separately from the source code - e.g. manual documentation as opposed to generating it using doxygen/sandcastle/javadoc) or am I stuck copying and pasting the same text into the source files of each version?
I was having the same issues and decided there were just two options for me:
Using the same documentation generator in all languages. If you use doxygen (or ROBODoc, or whatever) for all of them, you would have just one doc syntax for all languages. This means that you have to break with language-specific conventions, though.
Write your own doc parser. Which is hard work, especially for a language with quite complex syntactic rules (as C++.)
We are currently using doxygen for such projects.
Is there a place I can find Backus–Naur Form or BNF grammars for popular languages? Whenever I do a search I don't turn up much, but I figure they must be published somewhere. I'm most interested in seeing one for Objective-C and maybe MySQL.
you have to search on tools used to create grammars: "lex/yacc grammar", "antlr grammar" "railroad diagram"
http://www.antlr3.org/grammar/list.html
Here's some grammar files
objective-c
http://www.omnigroup.com/mailman/archive/macosx-dev/2001-March/022979.html
http://www.cilinder.be/docs/next/NeXTStep/3.3/nd/Concepts/ObjectiveC/B_Grammar/Grammar.htmld/index.html
https://github.com/pornel/objc2grammar
python
http://www.python.org/dev/summary/2006-04-16_2006-04-30/#the-grammar-file-and-syntaxerrors
javascript
http://tomcopeland.blogs.com/EcmaScript.html
http://www.ccs.neu.edu/home/dherman/javascript/
ruby
http://www.ruby-doc.org/docs/ruby-doc-bundle/Manual/man-1.4/yacc.html
FWIW, the MySQL grammar file (mysql-server/sql/sql_yacc.y) is open source and browseable at launchpad.net (though it's a bit slow and I got an error when I tried to pull up the specific file).
Also, a snapshot of the whole MySQL Server source is downloadable from dev.mysql.com.
There are some links from w:BNF#Language Grammars.
BNF Grammars for SQL-92, SQL-99 and SQL-2003
I also found a page that lists grammars for Objective C.
Objective-C grammar for Lex/Yacc Flex/Bison
Reference Manual for the Objective-C Language
IIRC, BNF grammars are just different enough from what yacc/bison want as input to be really annoying :) If you intend to feed these files into a parser generator, you may want to look for files in the appropriate format. I recall seeing such files for Java, JavaScript and C++ at one point. Probably as part of Eclipse, Firefox and GCC, respectively, but I can't remember for sure. I would assume you can find pretty much any parser input file by finding an open source project that uses that language.
I also searched this and i collected this repository
http://slps.github.io/zoo/