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.
The community reviewed whether to reopen this question 3 months ago and left it closed:
Original close reason(s) were not resolved
Improve this question
I've developed a pretty extense API, and I have it on Postman, which works pretty nice. Now I have to generate an html doc to keep it versioned inside /docs along with my sources.
Is there a tool or a way to achieve this? I really don't want to write all this documentation. Sharing the postman collection is not an option.
I recently had the same problem and I did not find anything. So I created a simple tool to do it. It is a very basic javascript application written with react.js. At the moment it is very basic, but I'm working on it, so any feature request is welcome.
You can use it for free at: http://www.vernizzis.it/docman/
Plus you can get the code and modify it at: https://github.com/davidevernizzi/docman
Any comment is more than welcome.
UPDATE1: looking around I also found this project: https://github.com/JakeWorrell/docodile
and this feature request: https://github.com/a85/POSTMan-Chrome-Extension/issues/204
UPDATE2: the feature request (see UPDATE1) has been closed and the possibility of creating documentation has been added to Postman cloud. Here is the feature request closing comment:
This is available as part of Postman Cloud: http://blog.getpostman.com/2015/12/10/introducing-postman-cloud/. Cloud hosts, updates and maintains documentation for everyone. I'd suggest http://docman.launchrock.com/ and https://github.com/JakeWorrell/docodile for generating one-time documentation from Collections.
I know this is an old question and you probably found a solution by now, but still you might be interested by Postmanerator: https://github.com/aubm/postmanerator
Basically, this is how you use it from the command line:
postmanerator -collection=/path/to/your/collection.js -output=/path/to/doc.html
To get it installed, download the latest Github release. You need to pick the appropriate binary depending on your system. Then place it somewhere in your PATH.
See the documentation in the README if you want additionnal information. From there you will find recommandations for taking full advandage of the tool, or change the look of your documentation by using custom themes.
The Github presentation also provides a reference to a generated example documentation.
You will also discover how you can take advantage of a CI platform like Travis, to automate the generation and the publication of your documentation with Postmanerator.
As this is an open source project I'm currently working on, feel free to submit issues on Github if you have any ideas that can make it better.
You can install Newman using command "npm install -g Newman" and then run the command "newman run CollectionName.json -e envVar.json" from the location where you have saved your collection, where CollectionName.json is your collection name and enVar.json is the set of environment variables. This will generate html report in the same folder.
One prerequisite is to have node js installed.
You can also try the free tool that I made. It provides the documentation in .txt but you can convert it to pdf using your browser.
https://postmandoc.herokuapp.com/
Related
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
The task
We'd like to maintain some developer's documentation for our .NET projects with the following criteria:
"Documents", ideally written in Markdown for providing information that's not closely related to a piece of code (like overview, FAQ).
Standard inline comments for code and API documentation. We do thus in form of standard inline (XML) comments on the classes/interfaces (primarily for IntelliSense support, secondarily for being able to generate an API reference) and would like to continue to do like that.
The documentation is contained in what it documents; e.g. if it's an overview of a solution then in the solution, if it's for a project then among the project's files, version controlled in the same way as the code (this is so the docs are close to what they document, so they are less prone for going out of date, and also this was docs are always "at hand").
Ability to auto-generate (from the CI server) a readable, compiled documentation for a whole project, including "documents" and inline comments for APIs.
An example
We've a project that's a component usable within a 3rd party system. For this project we have the following type of documentation:
Overview (what the project does, what are the aims)
Installation instructions
API documentation
Version history
We'd like to enable our developers and other developers to
- read this documentation from the project's source package and
- from a website.
Solutions we've looked at
Using a wiki (we tried Confluence): this is good for "document"-type of documentation (like overview or installation notes), but it lives independently from the project itself. It's another system to maintain and because it's not before one's eyes when doing development it can quickly go out of date. Also it's one more task to somehow integrate auto-generated API documentation into it.
Using Markdown files and storing them along the code: this is simple and documentation is always at hand and close to what it documents; however we somehow need to generate a publishable web package from these files and the source files' inline documentation.
So far doxygen looks like the solution capable of providing all these. Do you agree?
See "How to include custom files in doxygen".
Broadly speaking this is exactly what I am currently doing, and I'm using Doxygen.
However, I'm afraid I know nothing about .NET. The project I'm working on is a Java package, but includes API documentation extracted from the source, user guides, release records and things like deprecations.
The only thing out of our scope and in yours is Installation Guide, but that's really only because the developer only gets to read it after installation.
We have Jenkins CI building the document on every change.
The 'descriptive' text is all written in Markdown which Doxygen handles reasonably well.
Downsides: If you are familiar with the way Doxygen handles grouping of text for source code you may be confused that these commands don't work to group the blocks of text in Markdown. There are a few other specific oddities but you'll probably find most of them if you scan my own questions on the subject (here, here and here)
Upsides: (Things we've found useful that you've not mentioned)
We can also parse the 'doxygen' markup in the Java API to create a javadoc that IDE's such as Eclipse can use. This does mean we have to limit ourselves to javadoc-style command in the API docs but that's not a big limit.
We've included, under doxygen 'build switch', a manual for your developers on how to write the documentation for the manual (OK, this is slightly recursive!). This provides the recommended command subset to use, and whether (according to taste) you want people to use doxygen #subsection or Markdown ## for headings etc.
Hope that helps.
I'd suggest you try it; trialling a sample of each type of document section you need, to see if it will do the whole set of functions you need. Nothing more annoying documenting 90% then finding it won't do the last 10%.
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 6 years ago.
Improve this question
How can I use Go to call and manage Ldap protocol directly? are there any packages? or must I use udp and tcp?
There is no LDAP library in the Go standard libraries, but a quick Google search reveals several you could try:
https://github.com/mmitton/ldap
https://github.com/tonnerre/go-ldap
This second one is actually a fork of the first one. On github you can always view the open issues, last update and forking network (https://github.com/mmitton/ldap/network) to get a pretty good sense of which library you should use when there is a lot of forking.
If you need a library for something omitted in the Go standard libraries there are several good places to look:
Always start with a quick Google search
Checkout: http://go-lang.cat-v.org/pure-go-libs / http://go-lang.cat-v.org/library-bindings
And: http://godoc.org/
And: http://code.google.com/p/go-wiki/wiki/Projects
If all of those fail you and you don't feel up to creating your own implementation, keep in mind you can always use cgo to call C code (such as one of the many C LDAP libraries for example) from Go.
Thought I should add my ten cents here. It is an old post, but here it is nonetheless
I used the https://github.com/mavricknz/ldap library after using the mmitton/ldap one as mentioned by voidlogic above. The problem with the mmitton lib is that it does not handle escape characters very well in the filter.
The test filter: (&(objectClass=user)(cn=wickd(bracketTest )))
Escaped Filter: (&(objectClass=user)(cn=wickd\28bracketTest \29))
The MMitton library just came back with a filter compile error even with the escaped filter. Loaded the Mavricknz lib and it worked. Even comes with EscapeFilter function! brilliance!
Anyhow... Thought I should post this for anyone that had the same struggle as I did :)
I started to write a helper library for building server software capable of speaking the LDAP protocol.
There are some usage samples included.
https://github.com/vjeantet/ldapserver
Additionally, for the server end of it, I wrote this package (in Go) a while ago:
https://github.com/bradleypeabody/godap
It's not a full LDAP server but works well for implementing authentication on top of another data source (something I have been unable to find any other project that addresses).
It does a lot of "manage Ldap protocol directly" :)
For a simple high-level ldap client, see go-ldap-client, go docs.
Most of the options on https://godoc.org/?q=ldap
are just forks of another one, most of them are too low level or too limited (e.g. do not return errors
which make it hard to troubleshoot issues).
If you want to provide LDAP based authentication on your web page, you may like the solution I created: go-ldapc is a LDAP Authentication Client Module, with only one API.
It's on github - sona-tar/go-ldapc.
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 am looking into using a wiki (prefer mediawiki, but not a req.) as the repository for developer generated documentation (User Guides, Release Notes, Application Notes, Errata, etc.) from a collaborative/easy-to-update point of view a wiki seems like a good match, however since this documentation will ultimately ship to customers we want to be able to export the documents in their final state (e.g. during the release cycle) to static versions that no longer include histories.
Ideally the export would leave the document in a form (i.e. word doc, or legible HTML) where updates could be easily made by a non-programmer.
It would be good if niceties like section ordering and table of contents were available, or easy to add after the fact.
Are any tools with features like these available?
It sounds like you need a step in your dev cycle that will take your HTML wiki contents and "documentify" them - doc/pdf/html for simpler delivery. If that's right, you could try something like Docmosis or JODConverter which can act as engines to do the conversion. The last step would be working out how to integrate it and have it automatically extract your wiki content to transform into a document.
I'm a little confused.
If you want to ship the documentation in a formal like HTML, how would users continue editing? (use DumpHTML to generate HTML).
If you want to ship the documentation in Wiki form and allow users to continue editing, why not just replicate the database and get rid of the change history until a certain point? AFAIK MediaWiki has some support for this.
One option would be Mylyn WikiText, which is used by some Eclipse projects to generate Eclipse documentation from the Eclipse wiki (which is based on mediawiki). WikiText also supports other wiki markup (trac, textile, etc.) and other output formats (docbook, HTML, etc.).
In MoinMoin Wiki you can export to DocBook. DocBook can be converted to professional looking PDFs.
DokuWiki uses plain text files as storage backend which can be simply copied to your project as documentation.
First, don't discount that MediaWiki has a permanent link function. So, if you allow the readers to access your wiki, you can just send them a URL to a specific version of the page.
Alternatives - you can print a PDF. Wikipedia uses the Collection extension but there are others.
Finally, if you use Firefox and want a client side solution, use PrintPDF
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 have a project under continuous integration and would like to add end user documentation to the project. The end user documentation is a user manual, not API documentation. In our environment we use windows, c#, msbuild, cruisecontrol.net and subversion. We are currently using DocToHelp to create our help file, which is based on an msword document.
I'm looking for some guidance on how to manage the end user documentation. What documentation tools should I use? Should any of the documentation tools be part of the build script? Should the output files from the documentation tool be stored in subversion? What type of help files would be best to use?
We has been using XMLMind XML Editor to produce user documentation in the unified docbook format that can be stored in a version control system for the past 6 years. We use standard XSL transformations to generate user documentation from docbook in HTML and PDF format. Of course, this all is a part of the Continuous Integration and release build cycle.
Hope this helps.
I don't know DocToHelp but here is my take:
Even if it's the only thing you do: Start with adding your generated help file and all the files you used to create it in your version control system.
If generating the help file is not much more then processing a Word doc file then perhaps I wouldn't bother integrating it on the CI server. Your CI server's build artifact folder will just contain the help file as fetched from version control.
If there is a whole bunch of files (perhaps externally linked images in the doc?) and there is a chance of failure you could add it (if the help file building tool allows).
Basically what your CI server would prove then is if it can reproduce your help file from version control (did you commit and add everything?).
Taking it even further you could build automated tests which would examine the build help file and compare it with the referenced helpcontext IDs in the software itself. But here I am speculating (I haven't done helpfiles in ages :-)).
You might want to take a look at Doxygen:
http://www.doxygen.nl/
Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#
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
Currently the documentation where I work is in a bit of a state. There isn't anywhere near enough of it, and the documentation that does exist is spread out over many word documents making it hard to find anything.
I'm trying to take some initiative and get it improved, and I figure the first thing is to find a better format to write the documentation in:
My thoughts are that the documentation should be structured in a series of short articles (MSDN / Html Help style) and structured in a suitable tree:
It would be good to be able to produce a standalone Html-Help style package to be shipped with the application
As well as being able to produce a MSDN-style website as a reference for those who are too lazy to look at the CD.
Search is of course a must-have
It needs to be at least reasonably easy to update - if there is a 17 step process to update the published documentation then it makes it seem like too much work to do simple changes, and nobody can ever be bothered to update it.
The documentation is technical in nature, and so ideally it would be nice to be able to include generated documentation from things like the Xml documentation embedded in C# code. This is however definitely a side-requirement - currently very little useful Xml documentation exists, its just that in the future I plan to fix that.
For the same reason it is often good to be able to handle things like attachments (code samples etc...) I'm not expecting anything fancy, but this is something I need to bear in mind to make sure that its at least not handled badly.
Are there any projects or languages that are suited to this sort of documentation?
I've had good results with doxygen on my C and C++ projects although it supports many other languages as well. You put the documentation in comments in the code that can be simple or complex HTML markup. It is very easy to update as it is part of the code. You can make building the documents part of your build process. Additional topic that are not strictly API related can be added as separate HTML documents. The version I'm using doesn't support search so you would have to add another product to search these pages. Because it is HTML you can add in code samples, diagrams, etc.
If you use LaTeX you can get all your documentation in great looking PDFs and printed copies, as well as being able to generate html (via latex2html). TeX has the advantage of being all plaintext, too, so you can track/merge it reliably with your favourite revision control system.
We use confluence as our documentation repository. It is fairly easy to have public and private sections, and has a nice WYSIWYG editor. It can handle attachments and can be saved off as PDF documents if you like.
I've used robohelp with good results. it is plain html, but has a generation process that keeps everthing looking consistent. It can be packaged as a .hlp file with the app, or published to the website. Check it out, it is simple so you can get back to doing your job :)
A clean way is to use DocBook. It is easy write and undetstand. It is also easy to parse as XML parsers are standard and other forms of documentation (e.g. from the embedded documentation in comments) can be easily be transformed to this format.
It is straightforward to generate PDF, HTML og other formats from the DocBook source (tools exist for this purpose).
I've started using DokuWiki. Its not exactly what I was originally looking for (I think I was really looking for a CMS), but it does the job and some respects its better than what I originally had in mind (in particular its a wiki - I've not yet gotten as far as publishing this to our customers however so I'm not sure how well thats going to work out)
I'm using the IndexMenu plugin and the Arctic template to get a navigation tree on the left, and if I publish the wiki itself I'll use the discussion plugin to allow users to post feedback.
Currently my method of handling generated content is to use xslt templates to produce dokuwiki syntax, and write that output directrly to files / folders in the "data/pages" folder.