nuxeo/doc.nuxeo.com

Name: doc.nuxeo.com

Owner: Nuxeo

Description: Nuxeo documentation

Created: 2016-05-10 12:46:16.0

Updated: 2018-04-17 14:54:57.0

Pushed: 2018-05-17 15:32:32.0

Homepage: null

Size: 16816

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

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
• Node.js — Stable: See Release schedule(version >= v6.9)
• nvm install v6 will get the latest v6 version
• Test with node --version
• Remember: nvm use v6 at the start of your session
• libsass
• A Markdown text editor (https://atom.io/ or https://www.sublimetext.com/ for example)
• EditorConfig plugin.

Mac:

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

date
 update
stall git and libsass
 install git libsass

Installation

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

clone https://github.com/nuxeo/doc.nuxeo.com
oc.nuxeo.com
install

Build locally

start

Host locally after build

run server

Run and host locally (watches changes)

run dev_server

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

Run a complete build so all pages are built.

start

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

repositories:
    platform:
        url: git@github.com: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

run dev_assets

Change browser

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

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

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

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

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

Then push the version commit and the tags:

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):

 doc.nuxeo.com-content
checkout master
pull
checkout -b 910

Configure new branch:

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

  ch: '910'
  browser_path: '910/nxdoc'
  ions:
  
  label: LTS 2017
  url_path: '910'
  is_current_version: true
  

Push new branch

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.