RandomSec/docs
Mattzee bc2099a6f4
Updated build-test-run.md no JDK later that 14.0.2 (#4280)
* Updated build-test-run.md no JDK later that 14.0.2 

Added a recommendation about JDK version to use.
Build-test-run.md sugguested to install the latest JDK which let's you build OpenRefine, but running it does not work see: 
https://github.com/OpenRefine/OpenRefine/issues/4106
This might be frustrating for beginners not aware of this issue.

* Update build-test-run.md

changed Java version recommendation according to disucussion on https://github.com/OpenRefine/OpenRefine/pull/4280

Co-authored-by: Antonin Delpeuch <antonin@delpeuch.eu>
2021-11-22 09:34:44 +01:00
..
docs Update contributing.md (#4275) 2021-11-07 14:52:04 +01:00
src feat: move to em from pixels (#3477) 2021-01-19 09:28:44 +01:00
static Remove trailing slashes in doc pages URLs to fix links. (#3821) 2021-04-24 15:33:24 +02:00
versioned_docs Updated build-test-run.md no JDK later that 14.0.2 (#4280) 2021-11-22 09:34:44 +01:00
versioned_sidebars Fix 3.5 docs 2021-11-07 18:34:58 +01:00
.gitignore begin Docusaurus 2 migration (#2799) 2020-06-29 08:45:24 +02:00
.node-version Update Docusaurus to 2.0.0-alpha74 (#3856) 2021-04-28 09:48:33 +02:00
crowdin.yml Crowdin integration to translate the docs (#4029) 2021-07-02 20:37:23 +02:00
docusaurus.config.js Fix docusaurus config so it fails on broken links. (#4032) 2021-07-04 18:43:32 +02:00
netlify.toml Crowdin integration to translate the docs (#4029) 2021-07-02 20:37:23 +02:00
package.json build(deps): bump @docusaurus/preset-classic in /docs (#4264) 2021-11-07 11:07:24 +01:00
README.md Mention about yarn upgrade for starting errors (#4069) 2021-09-26 14:09:01 +02:00
sidebars.js Document translation of docs (#4033) 2021-10-22 20:33:45 +02:00
versions.json Add docs for 3.5 2021-11-07 15:03:22 +01:00
yarn.lock build(deps): bump @crowdin/cli from 3.7.1 to 3.7.2 in /docs (#4313) 2021-11-20 21:26:05 +01:00

How to build these docs

We use Docusaurus 2 for our docs, a modern static website generator.

Requirements

Assuming you have Node.js installed (which includes npm), you can install Docusaurus with:

You will need to install Yarn before you can build the site.

npm install -g yarn

Installation

Once you have installed yarn, navigate to docs directory & set-up the dependencies.

cd docs
yarn

Local Development

yarn start

This command starts a local development server and opens up a browser window. Usually at the URL http://localhost:3000 Most changes are reflected live without having to restart the server.

If you get an error starting yarn mentioning update.latest such as

>yarn start

if (notifier.update && semver.gt(this.update.latest, this.update.current)) {
TypeError: Cannot read property 'latest' of undefined
    at Object.<anonymous> (E:\GitHubRepos\OpenRefine\docs\node_modules\@docusaurus\core\bin\docusaurus.js:49:46)
error Command failed with exit code 1.

then it is likely that you will need to first run

yarn upgrade

which will update all dependencies and store them in the yarn.lock file to also be committed.

Next version of OpenRefine docs

If you wish to work on the next version of docs for OpenRefine (master branch) then you will need to:

  1. Git checkout our master branch
  2. Edit files under docs/docs/
  3. Preview changes with the URL kept pointing to http://localhost:3000/next which will automatically show changes live with yarn after you save a file.

Build

yarn build

This command generates static content into the build directory and can be served using any static contents hosting service.

Deployment

GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the gh-pages branch.

Translations

It is now possible to translate the OpenRefine docs via the Crowdin platform:

https://crowdin.com/project/openrefine

Unfortunately, unlike Weblate, we need to manually invite anyone who wants to contribute translations. Feel free to request an invite by emailing us at openrefine-dev@googlegroups.com We can also add languages, depending on interest.

Your translations will not be immediately published on https://docs.openrefine.org, it will take a few days (at the next commit on the master branch). The translated pages will first appear under https://docs.openrefine.org/next/ (the documentation for the development version). When we publish a version, the translations for that version, we will take a snapshot of the translations during that time. We will trial this process for 3.5.