Skip to content

kaaproject/jekver

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Jekver

Tool to collect documentation from versions tags and update gh-pages branch in target repository

Configuration

CLI options

Run jekver with -h options to get latest cli help.

CLI overwrite configuraton loaded from config file so if option defined in config file and passed from CLI jekver will be excuted with values from CLI.

Configuration file

path Type Example Comments
project String kaa Project name
startFromTag String v0.8.1 Minimal version to collect documents
latest String v0.10.0 Latest version to generate redirection pages
addCurrent boolean false Flag to add current branch to the gh-pages
jekdocs Array Conversion rules to generate documentation
jekdocs[n].key Map Configuration Item
jekdocs[n].key.cmd String "mvn compile" Command to generate documentation
jekdocs[n].key.path String "path_to_mvm_proj" Base path from cmd should be executed
jekdocs[n].key.target String "" Target folder for documentation in gh-pages
jekdocs[n].key.copy Map dst:src Coping rules in format destination source #{version}/#{path}/#{src}/ -> #{key}/#{target}/#{dst}/#{version}

Basic usage

  1. Install Bundler to manage Ruby gems required for Jekver:

    gem install bundler
    
  2. Clone Jekver repository to the directory that contains your project repository with documentation.

  3. Install required Jekyll dependencies by running this command from the Jekver repository that you cloned in the previous step:

    bundle install --gemfile ./Gemfile
    
  4. In the cloned Jekver repository, open the gh-pages-stub/_config.yml file, specify title and baseurl parameter values for your project.

  5. Create a Jekver configuration file jekver.yml in the root of your project repository with documentation. For the docs parameter, specify the name of the directory that contains your documentation. If that directory is not in the project root, specify the full path from project root. See example below.

    project: MyProject
    latest: "current"
    
    jekdocs:
     - md:
         path: ""
         target: ""
         copy:
           docs: doc
    
  6. From the root of your cloned Jekver repository, run:

    ./jekver.rb -c <root path of your project repository>
    

    This will generate documentation structure and create two sub-directories in the root of your project repository: test-MyProject-pages-current and tmp.

  7. From the test-MyProject-pages-current directory, run jekyll serve. This will generate the documentation and serve it at http://localhost:4000/<baseurl>/.

Regenerate documentation after editing

You can use Jekver to locally view the changes you have made to your project documentation. To do this, you need to regenerate your project documentation after you have made the changes:

  1. Stop Jekver from running (press Ctrl+C in the same terminal where you previously run jekyll serve).

  2. Delete the test-...-pages and tmp directories from your project directory.

  3. From Jekver repository, run:

    ./jekver.rb --c <root path of your project repository>
    
  4. Go to the test-...-pages directory in the root of your project and serve the documentation regenerated in the previous step:

    cd ..
    cd ./test-gh-pages-current/
    jekyll serve