Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I'm looking into writing documentation about some functions but do not want to write the documentation in the source code.
Is there a template I can follow, e.g XML, or something which can generate some sort of Javadoc-ish looking style documentation?
There's docbook, but to be fair, docbook excels at book or manual style documentation. It does do website documentation, but its websites tend to not be as heavily interlinked as javadoc. This is an example of a docbook document rendered to a website.
Docbook excels when you have one "source document" that doesn't have a presentation in the real world, and a few "rendered documents" that all must contain correct, up to date information built from the source document.
It is hard to understand what you are looking for, mainly because it seems that you are not exactly sure yourself. Javadoc is documentation that was purpose designed to document Java code, so a "javadoc like documentation without source code" is a hard idea to follow. Perhaps if you sat down and thought about the main sections of documentation, you'd find an outline (which might heavily include the navigation you want to use). Then it would be much easier to fill in the blanks, because you have blanks.
You can use the javadoc engine to generate documentation. It is very configurable; and supports two kinds of plugins. One to add additional "tags" and one to add / override additional "layouts". However, these tags and layouts operate on an API that tends to be Java source code oriented, such that a "javadoc comment before a class" calls a method that effectively handles the javadoc for this class. As such, without Java source code (or something very like it) you have the wrong underlying API (unless you can bend it to your needs).
Maybe you are looking for something like Doxygen, an API-documentation tool that can also be used to write other documents (f.ex. the manual of doxygen was produced with Doxygen itself without normal source code.)
Another tool would be Sphinx, which can also be used for API-documentation and also manuals without source code (ex: Python documentation).
Related
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I'm the author of a fairly sized (and growing) framework. It primarily exposes JavaScript APIs, but also has public APIs in Ruby and a growing CoffeeScript segment. (CoffeeScript will eventually encompass most of the project, but there will always be a significant pure-JavaScript presence.)
Up until now, I've been documenting the JavaScript with PDoc and the Ruby with RDoc. Though I've no issues with RDoc, unfortunately PDoc is aging, high-maintenance, and requires a heck of a lot of typing that feels like superfluous clutter. Also, the transition of most of the code to CoffeeScript renders PDoc much less useful than it was.
Example of the project's current documentation
I've experimented with Rocco in a local branch and it works better than I expected. What's really nice is that it works with all my code, from Ruby to Coffee to JS. It's nice to see all the documentation in one place. It's kind of cool to see the source code next to the documentation, too, and this makes it very clear what a particular code segment is actually doing.
However, I am a bit worried about the overall structure. Docco/Rocco seems great for niche projects with very few public APIs, but its read-the-entire-project style strikes me as a double-edged sword. Though it's very informative, having to vertically scroll through the files without even a table of contents (not to mention, knowing which file to go to in the first place!) seems like it would make it difficult to actually find anything. Also, the default template required some hacking because the list of files was too long to be displayed. Not a huge deal but an annoyance, and a hint that this project may be out of Rocco's league.
I'm now considering CoffeeDoc. Judging just by the example, it seems promising, but it is of course Coffee-centric, which brings me back to running 3 separate documentation tools: RDoc, CoffeeDoc and -- what? JSDoc?
I'm not completely adverse to running separate tools for the separate sources, but it becomes hard to reconcile that into a coherent result that doesn't feel like 3 separate Web sites.
So I guess my question is: what tool do you use or suggest? What language(s) does it support? Is it easy to browse, read, and actually find a needle in the haystack that is your project? I'm even considering rolling my own tool at this point, except that I can't believe no one else has encountered a problem like this (and I don't really want to waste time if I don't have to).
Sphinx directly supports javascript. Documentation of Ruby and CoffeeScript is supported through extensions (https://bitbucket.org/birkenfeld/sphinx-contrib/).
From the website:
The following features are present, work fine and can be seen “in action” in the Python docs:
Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), manual pages, plain text
Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information
Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
Automatic indices: general index as well as a module index
Code handling: automatic highlighting using the Pygments highlighter
Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs), and more
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I'm investigating different documentation systems for a project keeping up. Most recently I've been using DITA and the DITA OT, but its complexity makes me want to shoot myself.
Are there any systems that provide the following functionality:
Markdown support
Reusable content (I can refer to previously defined paragraphs or terms)
Localization support
Preferably, free or open source
Preferably, allows for multiple output
I wish I could use Pandoc for this, but it doesn't appear to support reusable content.
Edit: I just ended up writing my own library for this: https://github.com/gjtorikian/markdown_conrefs
If you don't mind reStructuredText instead of markdown, Sphynx is worth a look.
You could use pandoc + pre or post processor.
That way you could easily implement snippet reuse.
This is a topic close to my heart. There's quite a lot of Markdown processor options out there, but at time of writing those are more a case of personal solutions to this persistent problem. We all tend to get frustrated, make something to help in the short term, and share it.
The challenge has been to extend this to something built for purpose and at scale. Which is where I've turned my focus to over the last few years. That includes first working on PressGang CCMS inside of a tech writing team at Red Hat, and then being inspired to spin out Corilla, a dedicated technical writing startup building the tool you require.
PressGang (the prototype)
Please refer to the PressGang CCMS project for an idea of what we did at Red Hat to build tools to solve this. The lead engineer did a run-through video that you can see on Vimeo, and I've created a public Amazon AMI if you wish to try it. It's not being maintained but it's all open source.
It's a relatively large stack written for the most part in Java, but was useful as a look into an open source project in this space. But with bias I'd suggest...
Corilla (the product)
We cofounded Corilla as an open source company to focus on bringing together the elements of content reuse and collaboration with the ease of Markdown and Asciidoc. I've spent years writing DocBook XML, and quickly built my own snippets for Sublime Text to minimise the considerable overhead of authoring in that markup. The tide is of course turning. We need easier ways to write faster, and we need them to be discoverable, reusable, and allow the entire team to generate the content in formats they require.
I'd encourage you to get involved with the beta, as the technical writing and developer community is driving the project, and as we solve our problems together. Being able to resource and drive this to market is far more rewarding than having to pick through incomplete processor chains. I've been there, it's time we did more.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 3 years ago.
Improve this question
I'm hoping to show a visualization of the code base which can show areas that are overly complex and intertwined.
I know what clang is, but I'm not sure it gives me what I want in this case.
AnalysisTool: I know it's a clang wrapper but it also provides dependency diagrams.
AnalysisTool was originally created to serve two main purposes: to provide an easy-to-use executable binary of Clang static analyzer and to customize Clang by providing some additional checks. When Clang static analyzer was in its early stages, the only option for developers to try it out was to check out the latest source code of LLVM and Clang, compile it, and use the analyzer from the command line. AnalysisTool provided an easy-to-use GUI interface and removed the need to touch Clang source code. It also provided automatic updates, so that users of AT could always use the latest Clang static analyzer.
lizard:
This tool will calculate the cycolomatic complexity of C/C++/Objective C code without caring about header files and preprocessors. So the tool is actually calculating how complex the code 'looks' rather than how complex the code 'is'.
People will need this tool because it's often very hard to get all the
include folders and files right with a similar tool, but we don't
really need that kind of accuracy when come to cyclomatic complexity.
These are the only two tools I know, hope this helps.
Our Source Code Search Engine provides the ability to search across large sets of source code in multiple languages, using the code structure of each language to guide the search and minimize false positive matches.
As a side effect of its indexing process, it computes various complexity metrics (Halstead, McCabe) for files and writes that to an XML file you can process/display any way you like.
It has language front ends for C and C++; either of them ought to be able to process Objective C well enough for the SCSE to operator, and for OP's purpose, to compute such complexity metrics.
The downloadable version has the C front end included.
Edit June 2019: It has an Objective C front end now.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 7 years ago.
Improve this question
Im trying to find a piece of software to help a small (~3-5 people) team write A) a user guide and B) an API reference for the extensible parts of the software. We quite like the idea of using a wiki of some form, but have a few specific requirements:
The ability to export the manual(s) into both online and offline readable forms (eg, a bunch of HTML files that can be put on a web server or read locally)
Automatically create pages from XML documentation. We are writing in VB.Net/C#.Net, and most of the API specific stuff already has XML documentation comments. It would be great if the API portion of the manual could specify the classes, methods, arguments etc, but also allow the writers to link to these pages from others. (eg, have a page that details the foo class, and be able to have a page that details how to do some general task with the API link to the page for the foo.increaseBarCount() method).
That's just about it, other than the obvious ('easy to use', 'do all the writing for me so that i can get out of the tedium of writing technical documentation', 'not cause a global thermonuclear war').
Does such a piece of software exist? Can a similar system be cobbled together using mediawiki extensions?
As to "automatically create pages from XML documentation", the obvious solution would by doxygen. It creates documentation (HTML, PDF, WinHelp ...) from special doc comments embedded in source code. It handles Javadoc comments, Qt style comments and XML comments. If you generate HTML, the page names are predictable, so easy to link to; doxygen can also create internal links automatically. If you use other formats, you can probably embed some sort of anchor to refer to page names, but I'm not quite sure about that.
With respect to general documentation, we have good experiences with using a wiki. We use MediaWiki (of Wikipedia fame), but any decent wiki will probably do.
We have never tried printing it, but Google shows various solutions for printing from MediaWiki, so you can probably make something work without too much hassle.
The main thing we like about using a wiki for docs is that you can easily change them when you detect a mistake; that keeps them fresh. Also, no worries about having an outdated copy.
You could check out Atlassian Confluence. I believe that they have a free version (possibly just an offer, so you may end up paying in the long run, don't know) for small teams. They also have an API, so it wouldn't be too hard to write a utility to extract the XML C# documentation and create pages from it using the API, if nothing already exists.
The wiki is easy to use and is used quite a bit by open source projects. You can look at
the ANTLR Documentation, which is Confluence, for an example.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
let's say that in order for me to make clear how my program works or even for the own sake of documentation I am writing some text document in word or whatever text editor or online wit google docs, etc. Let's say that at some part of the document I open a new one and extend there the idea. Then later, I go back to the "master" document and add some hyperlink or just put reference (it follows in doc XXXX, page YYYY). I wonder what could be the fastest approach to do this
* google docs adding easily hyperlink? but how can I organize docs effectively?
* some text editor with this functionality?
Thanks for your responses
P.D. Are there easier solutions than WIKI's? In terms of easiness of installation and setup
Wiki's are definitely great for that. I have used two notetaking solutions that have what you want (I've used more, but these were the best for me).
TiddlyWiki
Great feature set since it's javascript/html with wiki functionality: intralinking to pages you create, embedding of images from any directory, hyperlinks, and printability
Also has an amazing amount of plugins at places like TiddlyTools and other repos like it
I combined it with TeamTasks which not only made it look better, but brought in some todo functionality; with TiddlyWiki Address Book (twab) for contact management, and several other plugins that worked great
emacs + orgmode
This is my top choice today for notetaking and all kinds of stuff
It is literally unbelievable. Todos, contacts, scheduling, linking, export to html, export to PDF via LaTeX, interfacing with gnuplot, TikZ, ditaa, R (like Matlab), etc.
Inter and intralinking are very easy. See THIS for specifically how orgmode deals with various linking.
Lastly, if orgmode sounds interesting, I would strongly recommend checking out the orgmode wiki, Worg, where tutorials, videos, and screencasts exist.
Your initial inquiry mentions simplicity, so perhaps one of the wikis is best. If you're unfamiliar with them, it's quite easy to just download a copy (just an html file), open it in a browser and play around. There's a lot of documentation out there to help you and your linking is as often as easy as writing something like [[page::section]] or similar in your document.
On the other hand, if you're looking for advanced usage and especially exporting of documents, I have yet to find anything to beat orgmode for me! I highly recommend it and the mailing list is very, very active and supportive.
Every document type or system has its own standard for interlinking documents. HTML has hyperlinks, MS Word has document references, etc. I personally find wikis to be the easiest way to grow and expand interlinked documents. HTML hyperlinks are probably the most common standard way of linking documents, and wiki syntax makes it especially easy.