[Installing Natural Docs via the command line] #travis #gulp #bash #documentation #ci #macos

installing-natural-docs-via-cli.md

Installing Natural Docs via the command line

Use of Natural Docs requires installation of several dependencies:

• Mono - a .pkg (for MacOS), downloadable from https://www.mono-project.com/download/stable/
• Natural Docs - a .zip file, downloadable from https://www.naturaldocs.org/download/

---

Attempt 1

In my first attempt, I did different things for my Local dev environment and the CI (Travis).

Mono

Local: Download and Installation

Manually download and install Mono.

CI: Download and Installation

# .travis.yml

before_install:
  # Install Mono (Natural Docs dependency)
  # https://www.mono-project.com/download/stable/#download-lin-ubuntu
  - sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF
  - sudo apt install apt-transport-https ca-certificates
  - echo "deb https://download.mono-project.com/repo/ubuntu stable-xenial main" | sudo tee /etc/apt/sources.list.d/mono-official-stable.list
  - sudo apt update
  - sudo apt install mono-complete

Natural Docs

Local: Download and Installation

1. Manually download Natural Docs and copy to the globally accessible Applications folder.

CI: Download and Installation

# .travis.yml

before_install:
  # Install Natural Docs
  # Unzips to 'Natural Docs'
  - sudo apt-get install unzip
  - wget https://naturaldocs.org/download/natural_docs/2.0.2/Natural_Docs_2.0.2.zip && unzip Natural_Docs_2.0.2.zip

Both: Generate Documentation

// gulpfile.js

/**
 * Function: is_travis
 * 
 * Determines whether the current Gulp process is running on Travis CI.
 *
 * See: <Default Environment Variables: https://docs.travis-ci.com/user/environment-variables/#Default-Environment-Variables>.
 *
 * Returns:
 *   (boolean)
 */
function is_travis() {
    return (typeof process.env.TRAVIS !== "undefined");
}

/**
 * Method: docs
 * 
 * Generate JS & PHP documentation.
 *
 * Returns:
 *   Stream or promise for run-sequence.
 */
gulp.task("docs", () => {

    gulp_helper_taskheader(
        "5",
        "Documentation",
        "Generate",
        "All (PHP & JavaScript)"
    );

    let naturaldocs_path = "";

    if ( is_travis() ) {
        // Travis install
        // Quotes escape space better than backslash on Travis
        naturaldocs_path = "Natural Docs/NaturalDocs.exe"; // eslint-disable-line quotes
    } else {
        // Local install
        naturaldocs_path = "/Applications/Natural Docs/NaturalDocs.exe"; // eslint-disable-line quotes
    }
});

---

Attempt 2

Mono

Both: Download and Installation

As per Attempt 1.

Natural Docs

Both: Download and Installation

Removed Natural Docs code from .travis.yml

Added a new Gulp task which downloads Natural Docs and extracts it to the current working directory.

Note: Natural Docs can't be installed via Yarn, as the Github release needs to be compiled, and the download archive on the website is in .zip rather than .tar format.

// gulpfile.js

/**
 * Function: dependencies_docs
 * 
 * Install documentation dependencies.
 * 
 * Natural Docs can't be installed via Yarn
 * as the Github release needs to be compiled,
 * and the download archive on the website
 * is in .zip rather than .tar format.
 *
 * Returns:
 *   Stream or promise for run-sequence.
 */
gulp.task("dependencies_docs", () => {

    gulp_helper_taskheader(
        "1a",
        "Dependencies",
        "Install",
        "Docs"
    );

    const url = "https://naturaldocs.org/download/natural_docs/"
    + "2.0.2/Natural_Docs_2.0.2.zip";

    // return stream or promise for run-sequence
    return download(url)
        .pipe( unzip() )
        .pipe( gulp.dest("./" ) );
});

Both: Generate Documentation

Updated the existing function to remove the CI fork:

/**
 * Function: docs
 * 
 * Generate JS & PHP documentation.
 *
 * Returns:
 *   Stream or promise for run-sequence.
 */
gulp.task("docs", () => {

    gulp_helper_taskheader(
        "4",
        "Documentation",
        "Generate",
        "All (PHP & JavaScript)"
    );

    // Quotes escape space better than backslash on Travis
    const naturaldocs_path = "Natural Docs/NaturalDocs.exe";

    // note: src files are not used,
    // this structure is only used
    // to include the preceding log()
    return gulp.src(dummyFile, {read: false})
        .pipe(shell([
            `mono "${naturaldocs_path}" ./config/naturaldocs`
        ]));
});