7

I'm searching for a tool that can generate static HTML pages from markdown files. So far so good, there are plenty out there:

My problem is that I would like to write documentation for a selfcontained software repository. It should work like the following:

  • Developer starts up his workstation (Standard Windows 7)
  • Developer checks out repository (containing markdown files and the tool to generate)
  • Developer runs the doc-generation, let's say by calling createDocs.bat
  • Developer opens the generated index.html in his browser

My problem now is that all of the above mentioned tools need some kind of environment set up beforehand: node.js, Python and additional modules, ... However the idea behind the selfcontained environment is

  • It runs on offline hosts
  • It runs on hosts where it is not possible to install software
  • It runs behind a corporate proxy

Does somebody know a good tool which would work that way? Are there ways to get the above mentioned tools to work? I just tried a lot of things like converting mkdocs with py2exe but haven't had success...

Improve this question
1
  • Why is It runs on hosts where it is not possible to install software a requirement? You've used the word "Developer"; presumably he has some control of his machine and can "install software", you even insist he can "check out reposittory" meaning he must have (as a practical matter) installed version managment software.
    – Ira Baxter
    Commented Aug 8, 2015 at 6:05

2 Answers 2

Reset to default
3

Doxygen

Doxygen is a general purpose code documentation tool. It supports Markdown starting from version 1.8.0, and it can generate static HTML files among many other formats.

Features:

  • Cross-platform. Runs on all versions of Windows since XP
  • Has a portable installation that you could bundle with your repository so it would run offline and without Administrator privileges:

Your required workflow can easily be achieved with doxygen:

Improve this answer
6
  • 1
    With most VCSs it is a really bad idea to check in binaries - there is a lot of discussion on the net as to why but basically if it isn't source code it doesn't belong in the VCS.
    – Steve Barnes
    Commented Jun 21, 2015 at 14:35
  • @SteveBarnes True. In this case, checking in the configuration and batch files is sufficient, as anyone could download and run the executable from Doxygen website.
    – Tymric
    Commented Jun 21, 2015 at 15:11
  • 1
    In my understanding it's not bad to check in binaries per se. It's just a problem if you also have the sources available (then it's redundant). In case of doxygen or other thirdparty it's a good way to guarantee that the environment with which the software is built stays the same.
    – MOnsDaR
    Commented Jun 21, 2015 at 16:18
  • @MOnsDaR There's definitely no rule against it. I think most arguments state that since you can't use VC tools (like diff) on binaries, there's no sense in versioning them. But in your case, I think the convenience of having the executable in a specific path is a good enough reason to include it.
    – Tymric
    Commented Jun 21, 2015 at 16:28
  • 1
    Some, (many), VCS systems get very slow and unwieldy when they have binaries stored in them - my preferred approach is to have a known location where one or more specific versions of the input binaries are stored and a version controlled script that fetches the required version. It is then still a two step process - update from VCS then make, (just the same as if the tool was in the VCS). you can tie into a specific version of the tool for a given version of your source, etc. Also in the company that I work for there is a specific rule against it.
    – Steve Barnes
    Commented Jun 21, 2015 at 16:59
4

I can think of a few options for you:

Self Contained Binaries

  1. Portable Python - You would probably need to pick one of the document generators above, or possibly Sphinx, and add it to your portable python "installation".
  2. Pandoc built as a relocatable binary as explained here.

Both of the above meet the requirement of:

  • It runs on offline hosts
  • It runs on hosts where it is not possible to install software
  • It runs behind a corporate proxy

But in either of the above cases I would strongly recommend modifying your desired workflow to add a step of "developer downloads and unpacks the tool" since there are a lot of reasons not to put binaries into revision control systems and many corporate VCSs have specific policies to prevent you doing so.

Server within firewall

The other option might be to create an online document generation server but behind the corporate firewall. This would not work offline but would provide a lot more control of what software is used this could also be integrated with the VCS via hooks so that the workflow is modified to:

  • Developer starts up his/her workstation
  • Developer Checks out the repository - they must be online to do this
  • Post checkout hook submits the markdown to the document generator server, while they are still online, which generates the html on their local drive.
  • Developer makes changes to the markdown - this could be done offline.
  • Developer generates html from the modified markdown to check their work - either need to be online or have a local install of the same tool to do this.
  • Developer commits changes again need to be online for this anyway

This does not meet your first requirement but does give some advantages:

  • You can use just about any tool you need
  • There are no issues with version controlling tools
  • Your developers do not all have to be running Windows
  • Your document generator can have access to resources that you may not wish to install on the developers machine, e.g. the html could include reports generated from your issue tracking system or from a progress reporting system.
Improve this answer
1
  • I already thought about setting up a server to generate the documentation. Both methods have their own advantages. Will discuss that tomorrow.
    – MOnsDaR
    Commented Jun 21, 2015 at 16:22

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.