doc.nuxeo.com

Development

Requirements

• Git - make sure your Privacy & Security settings allow to download applications from anywhere
• Git-LFS
• SSH key associated with GitHub.
  • Test access with ssh -T [email protected] - see here for help.
• Node.js — Latest Active LTS: See Release schedule(e.g. v8.11.3)
  • nvm install will get the correct version to use from .nvmrc.
  • You should run this at the start of your session to ensure the correct version is in use.
  • The version can be verified by running node --version
• Markdown capable editor: e.g. Atom, Sublime Text or similar.
  • The Atom Documentation plugin-This plugin provides suggestions for {{file ...}} and {{page ...}} links.
• EditorConfig plugin (Recommended)

• libsass

Mac:

• Install homebrew (http://brew.sh/) and run

# Update
brew update
# Install git and libsass
brew install git libsass

Installation

Clone the repository to your local machine, using your favorite Git client or the command line:

git clone https://github.com/nuxeo/doc.nuxeo.com
cd doc.nuxeo.com
npm install

Build locally

npm start

Host locally after build

npm run server

Run and host locally (watches changes)

npm run dev_server

Run re-compile for assets and host (watches changes)

Run a complete build so all pages are built.

npm start

To speed up the build you can comment out versions in config.yml with #. e.g.

    repositories:
        platform:
            url: [email protected]:nuxeo/doc.nuxeo.com-content.git
            branches:
                - static
                - master
                # - '710'
                # - '60'
                # - '58'

710, ,60 and 58 have been commented out so only the static content and FT platform spaces are built.

Then run the following to host and watch for client asset changes

npm run dev_assets

Change browser

The browser defaults to chromium-browser but can be changed with the following command and then locally as usual.

npm config set Nuxeo-documentation-content:browser firefox

Writing Documentation

Writing Documentation Guide.

Releasing changes

As this module is used via npm, it's a good practice to bump the version when we make changes.

Node packages follow Semantic Versioning (SemVer), versions a described by a MAJOR.MINOR.PATCH version.

Recompile the client assets

npm run compile
git add assets lib
git commit -m 'Client Assets: Recompiled'

After you've committed your code, run one of the following:

npm version major # incompatible API changes
npm version minor # add functionality in a backwards-compatible manner
npm version patch # backwards-compatible bug fixes

Then push the version commit and the tags:

git push && git push --tags

Project Structure

./assets/...

Any files in this directory will be copied to ./site/assets. See ./site/...

./client/...

Client side styles (SCSS) and JavaScript.

./docs/...

./layout/...

Templates and partials. See working with templates.

./modules/...

Nuxeo specific modules.

./site/...

Generated output of the site. This is what will be served in production.

./test/...

Unit tests for modules.

./verify/...

Verification tests for post asset and site building.

./build.js

The main build script for generating the output for site.

./config.yml

Site configurations, ability to have production or development specific values.

• site.new_version: '{version number to match}' for NEW tag
• site.review_period: '{number} {days, months, years}'
• site.review_release_date: {date - YYYY-MM-DD}

./package.json

Build processes are defined here. Should be relatively self explanatory but anything special will be explained here.

Trouble shooting

Trouble shooting guide

Algolia DocSearch

• Crawling configuration: https://github.com/algolia/docsearch-configs (specifically: https://github.com/algolia/docsearch-configs/blob/master/configs/nuxeo.json)
• Implementation Documentation: https://community.algolia.com/docsearch/documentation/

Creating a new content branch.

In the Content repository (doc.nuxeo.com-content):

Create branch (e.g. 910):

# on doc.nuxeo.com-content
git checkout master
git pull
git checkout -b 910

Configure new branch:

• Open ./config.yml
• Update:
  • default > site > branch
  • default > site > dev_browser_path
  • default > site > versions e.g.

    branch: '910'
    dev_browser_path: '910/nxdoc'
    versions:
      -
        label: LTS 2017
        url_path: '910'
        is_current_version: true
    

Push new branch

git push --set-upstream origin 910

Adding/removing content versions to be published

In the Builder repository (doc.nuxeo.com):

1. Create a new branch from master: git checkout -b add/remove-version-xx e.g. adding 9.10 would be git checkout -b add-version-910
2. Open config.yml.
3. Add/Remove entry in default > site > repositories > platform > branches.
4. Rebuild to preview site.
5. Merge into master to Go Live.

Licenses

Code is licensed under a GNU GPLv3 and content
is under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.