Convert docfu from python to node or replace with Jekyll

[feltnerm]

Right now our documentation is generated via docfu. The main reason for doing this doc generator being written in Python rather than JS is the documentation server host does not have node.js installed on their system.

I'd like to convert the docs generator to node, make the api accessible via grunt, cli, or just require, and be able to use that for this project. This would keep the entire project in line with the fact that it is a javascript project. The generator would most likely use a bunch of pre-existing modules. My only issue is the availability of node on shared hosting.

There are a few options I can think of:

Keep current workflow

Pros:

• Proven success

Cons:

• High barrier to understanding the docs build in the context of the (javascript) project since it is written in Python/PHP.

Deploy the documentation somewhere

Convert documentation generator to Javascript. Use a javascript Jinja2 parser. Create the documentation locally -- or have on a server which listens to GitHub hooks -- and then send the compiled assets to a host.

Pros:

• Little to no conversion (docs stay as Jinja2 templates)
• Similar workflow to current
• Lower barrier to access since it is in Javascript/Node.js

Cons:

• Does it cost more to run a GitHub hook listener app than just a static site that is deployed to manually?
• Time to port the doc generator to js / create a hook listener

Move the documentation to GitHub using Jinja2

Convert documentation generator to Javascript. Use a javascript Jinja2 parser. Create a new repo (fine-uploader-docs) which will serve as the content host for the documentation where everything is hosted in gh-pages. The build scripts are in master. Could use existing node modules to do a lot of the heavy lifting.

Pros:

• Free and reliable content hosting
• Simple/easy to compile the docs and set up build scripts for them

Cons:

• Converting the build tool to js
• Is it possible to keep the same URL scheme?
• Other (un)/known incompatibilities

Move the documentation to GitHub using Jekyll

Convert the documentation and templates from Jinja2 syntax to Jekyll-compatible template syntax. Create a new repo (fine-uploader-docs) which will serve as the content host for the documentation. A more extreme option (most likely not possible due to sub-domains) is to move the docs to the main repository's gh-pages.

Pros:

• Free and reliable content hosting
• Running/Compiling locally may be easier (more guides on how to deploy Jekyll than docfu, haha)

Cons:

• Converting the templates
• Is it possible to keep the same URL scheme?
• Other (un)/known Jekyll incompatibilities

[rnicholus]

:thumbsup: My limited experience with jekyll has been positive.

[rnicholus]

Sems docfu is working well enough for us. Any plans to overhaul it, @feltnerm?

[feltnerm]

@rnicholus -- I'd still love to overhaul it simply because I think it should be easier to develop against our documentation generator, and it should be easier to compile the docs.