Eagle Documentation

Eagle documentation repository for content available on http://eagle.incubator.apache.org/docs/

Documentation is written in Markdown format and statically generated into HTML using MkDocs. All documentation is located in the eagle-docs directory, and mkdocs.yml file describes the navigation structure of the published documentation.

Requirements

Installation

  1. Validate versions of Python (tested under python 2.7) and python package management tool

     $ python --version
    
     # At least one of follow python package management tools should be installed
     $ easy_install --version
     $ pip --version
    

NOTES

MkDocs is built upon Python, before starting to install MkDocs, please make sure you verify at least one python package management tool like easy_install or pip has been installed

  1. Install MkDocs: http://www.mkdocs.org/#installation

     sudo easy_install install mkdocs
    

or

  sudo pip install mkdocs

Reading

Execute mkdocs serve under project base where mkdocs.yml is and open http://127.0.0.1:8000/ to start reading.

cd incubator-eagle
mkdocs serve

Authoring

New pages can be added under eagle-docs or related sub-category, and a reference to the new page must be added to the mkdocs.yml file to make it availabe in the navigation. Embedded images are typically added to images folder at the same level as the new page.

When creating or editing pages, it can be useful to see the live results, and how the documents will appear when published. Live preview feature is available by running the following command at the root of the repository:

mkdocs serve

For additional details see writing your docs guide.

Site Configuration

Guides on applying site-wide configuration and themeing are available on the MkDocs site.

Deployment

Deployment is done in two steps. First all documentation is statically generatd into HTML files and then it is deployed to the eagle website. For more details on how conversion to HTML works see MkDocs documentation.

  1. Go to release branch of the repository and execute the following command to build the docs.

    Note: Until mkdocs #859 is resolved and available for download, use mkdocs built against master.

    # set project version
    EAGLE_VERSION=0.3.0
    
    # build docs under site foolder
    mkdocs build --clean
    
    # copy docs from site into target folder on eagle-site
    cd ../incubator-eagle-svn
    cp -r ../incubator-eagle/site site/docs/${EAGLE_VERSION}
    # Set this to be latest available docs version
    git add -A
    git commit -m "Adding eagle-${EAGLE_VERSION} documentation"
    git push
    
  2. Add link to landing site

    TODO