kitsonk/dojoment

Next Generation Dojo Documentation Project

dojoment

dojoment is an experimental project looking at the possibility of a markdown based community editable documentation wiki which can be used instead of the current solution which is based on reStructuredText.

The main objectives of this project are:

• Base the entire solution on JavaScript (because that is what we are about)
• Leverage as much of the Dojo Toolkit as possible (eat our own dogfood)
• Adopt markdown as the primary markup
• Extend the markdown syntax, if required, to provide live examples
• Provide a community editable wiki
• Make it easier to generate final documentation for the website
• Fully integrate into git and GitHub for documentation storage
• Assess the suitability to be able to create Dojo Tutorials
• Align better with the Dojo Inline Documentation Parser

Licensing

This is released under the same "New" BSD License as the Dojo Toolkit:

• The "New" BSD License

(Note: It is not licensed under the AFL 2.1)

Additional libraries are licensed and copyrighted by their respective owners.

Requirements

• Node.js - Requires v0.8 or later (including npm)
• Dojo Toolkit - Requires v1.8.0 or later
• express - Requires v3.0.0 or later
• jade - Requires v0.27.2 or later
• marked - Requires v0.2.5 or later (customized)
• highlight.js - Requires v7.1.0 or later
• stylus - Requires v0.29.0 or later
• Font-Awesome - Requires v2.0 or later
• setten - Requires v0.1.1 or later

The Dojo Toolkit and Font-Awesome and the customized fork of marked are installed as submodules and can be managed by git. express, jade, highlight.js and stylus are installed as node modules and can be managed via npm.

Installation

Experimental does mean experimental, this is under heavy development and I may not remember to update the README every time.

• Ensure you have git, Node.js, npm and installed.

• You will also need cpm or volo to install the AMD dependencies.

• Clone the repository recursively:

   git clone --recursive https://github.com/kitsonk/dojoment.git

• Update the config.json.

• Update the reference docs repository:

   cd dojoment/refdocs
   git pull

• Install AMD dependencies.

  • Using cpm:

     cd ..
     cpm --packages-path=src install dojo
     cpm --packages-path=src install dijit
     cpm --packages-path=src install setten

  • Using volo:

     cd ..
     volo install -amd

• Build the client library build:

   src/util/buildScripts/build.sh --profile dojoment.profile.js

• Start the server:

   node server

You will get a message indicating that the server is running and what port it is running on.

Generating Static Documentation

In order to generate all the reference documentation

dojoment's Issues

running the client library build fails

dojo/util was cloned with: git clone https://github.com/dojo/util.git src/util

src/util/buildscripts/build.sh --profile src/dojoment-client/profile.js
processing profile resource /bks/BUILD/dojoment_git_bld/src/dojoment-client/profile.js

/bks/BUILD/dojoment_git_bld/src/util/build/buildControl.js:335
require.computeAliases(bc.aliases, (bc.aliasesMap = []));
^
TypeError: Object function (a1, a2, a3){
return contextRequire(a1, a2, a3, module, result);
} has no method 'computeAliases'
at /bks/BUILD/dojoment_git_bld/src/util/build/buildControl.js:335:11
at /bks/BUILD/dojoment_git_bld/src/util/build/buildControl.js:376:4
at runFactory (/bks/BUILD/dojoment_git_bld/src/dojo/dojo.js:1094:43)
at execModule (/bks/BUILD/dojoment_git_bld/src/dojo/dojo.js:1223:5)
at execModule (/bks/BUILD/dojoment_git_bld/src/dojo/dojo.js:1214:12)
at /bks/BUILD/dojoment_git_bld/src/dojo/dojo.js:789:7
at guardCheckComplete (/bks/BUILD/dojoment_git_bld/src/dojo/dojo.js:1238:5)
at contextRequire (/bks/BUILD/dojoment_git_bld/src/dojo/dojo.js:788:6)
at result (/bks/BUILD/dojoment_git_bld/src/dojo/dojo.js:808:13)
at /bks/BUILD/dojoment_git_bld/src/util/build/main.js:83:2

giving up now... just wanted to see dojoment in action...

Why will we use Markdown for Dojo2 instead of RST?

Traditionally, Dojo has been using RST for the Reference Guide and it's worked really well.

RST is so much more extensible than MD. In the dojoment website you said we will extend markdown to support things like live examples. With RST I don't think we need to do that.

For a newbie too, it isn't all that difference. I learnt RST first, then Markdown.

I'd like to know the advantages of MD over RST. I completely agree with you when you say we must eat our own dogfood and I'm sure there are node.js libraries that can parse RST (instead of the more popular Python environment for the same).

Please see the top voted answers for http://stackoverflow.com/questions/34276/markdown-versus-restructuredtext

project build problems

This url in .gitmodules

[email protected]:kitsonk/marked.git

causes

Permission denied
fatal: The remote end hung up unexpectedly
Clone of '[email protected]:kitsonk/marked.git' into submodule path 'src/marked' failed

using git clone without recursive succeeds, but subsequent git submodule init followed by git submodule update causes

git submodule update
Cloning into '_static/Font-Awesome'...
remote: Counting objects: 7261, done.
remote: Compressing objects: 100% (1894/1894), done.
remote: Total 7261 (delta 4148), reused 6617 (delta 3568)
Receiving objects: 100% (7261/7261), 5.83 MiB | 6.19 MiB/s, done.
Resolving deltas: 100% (4148/4148), done.
Submodule path '_static/Font-Awesome': checked out '13d5dd373cbf3f2bddd8ac2ee8df3a1966a62d09'
Cloning into 'refdocs'...
remote: Counting objects: 65, done.
remote: Compressing objects: 100% (27/27), done.
remote: Total 65 (delta 23), reused 65 (delta 23)
Unpacking objects: 100% (65/65), done.
Submodule path 'refdocs': checked out 'cf7a4f155b74bfa735a5255d5e043c139f8d3b6b'
Cloning into 'src/marked'...
remote: Counting objects: 2042, done.
remote: Compressing objects: 100% (957/957), done.
remote: Total 2042 (delta 913), reused 1813 (delta 704)
Receiving objects: 100% (2042/2042), 341.24 KiB | 340 KiB/s, done.
Resolving deltas: 100% (913/913), done.
fatal: reference is not a tree: 55aa5f9ebd626c844a841c26b54e61f395c76fd4
Cloning into 'src/util'...
remote: Counting objects: 8019, done.
remote: Compressing objects: 100% (2458/2458), done.
remote: Total 8019 (delta 5363), reused 7958 (delta 5312)
Receiving objects: 100% (8019/8019), 79.39 MiB | 6.64 MiB/s, done.
Resolving deltas: 100% (5363/5363), done.
fatal: reference is not a tree: 57bdb06edefddf1fcbc0d4a072c5c5b96b9f2950
Unable to checkout '55aa5f9ebd626c844a841c26b54e61f395c76fd4' in submodule path 'src/marked'
Unable to checkout '57bdb06edefddf1fcbc0d4a072c5c5b96b9f2950' in submodule path 'src/util'

Migrate Export to JSFiddle to page UI

The export to JSFiddle should be right from the main page, alongside the Run, Code and Collapse buttons.