diff --git a/README.md b/README.md index 7fcea69dc..d86fa9306 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ modifications you wish to contribute, fork this project, make the changes and submit a pull request. You will need to sign the contributors license agreement, which will be emailed to you upon creating the pull request. -This project is built using [Jekyll](https://jekyllrb.com/). +This project is built using [Antora](https://antora.org/). ## Contributing to the TinyMCE Documentation @@ -29,59 +29,6 @@ The following procedure assists with building (or compiling) the documentation l You need the following programs installed on your computer: -- Ruby version 2 or later. To verify the installed version, run: - ``` - ruby --version - ``` - -1. Install git, g++, `make`, and the zlib development files. For example: - - On Fedora, run: - - ``` - sudo dnf install git-all gcc-c++ make zlib-devel ruby-devel - ``` - - On Ubuntu, Debian or their derivatives, run: - ``` - sudo apt install git gcc cpp make zlib1g-dev ruby-dev - ``` - -2. Install Ruby Nokogiri: https://nokogiri.org/ - ``` - sudo gem install nokogiri - ``` - -3. Install Ruby Bundler. Install using: - ``` - sudo gem install bundler -v 2.2.19 - ``` - -4. (optional) Docker - -##### Windows users - -If you are a Windows user, follow these steps to work on TinyMCE documentation: - -1. Install [git for Windows](https://gitforwindows.org/). - -2. Install [Ruby+Devkit](https://rubyinstaller.org/downloads/). - -3. Run the following command on a command prompt to install Ruby Bundler: - ``` - gem install bundler -v 2.2.19 - ``` - -##### Mac OS users - -1. Ruby version 2 or later is required. Verify the pre-installed version, using: - ``` - ruby --version - ``` - -2. Install Ruby Bundler, using: - ``` - gem install bundler -v 2.2.19 - ``` - #### First time set up Once you have installed any missing prerequisites, in a terminal or on a command prompt: @@ -96,9 +43,9 @@ Once you have installed any missing prerequisites, in a terminal or on a command cd tinymce-docs ``` -3. Run the initialization script to install dependencies and create the required local files in the git repository: +3. Run yarn install ``` - ./_scripts/init.sh + yarn install ``` #### Run the development version of the documentation @@ -106,15 +53,19 @@ Once you have installed any missing prerequisites, in a terminal or on a command To create a development version of the documentation, run: ``` -./_scripts/serve.sh +yarn build +yarn serve ``` -Allow the `serve.sh` script to run in the background while you are working on the TinyMCE documentation. -To view the documentation; in a web browser, navigate to [http://localhost:4000/](http://localhost:4000/). +To view the documentation; in a web browser, navigate to [http://127.0.0.1:4000](http://127.0.0.1:4000). > **Note**: The development version of the documentation will update automatically when you save changes locally. +The `yarn build` step will download the latest TinyMCE source code and generate new API content. To change the version of TinyMCE API, open the `_scripts/api-reference.sh` file and edit the API_VERSION to the TinyMCE version you would like to generate API docs for. Alternatively, to build using a local version of TinyMCE, `yarn build-local ../path/to/local/TinyMCE`. + +**Note**: The development server does not need to be stopped prior to running the `yarn build` command, antora should pick up the new changes generated by the build step. + #### TinyMCE API documentation The TinyMCE API documentation is maintained within the [TinyMCE project repository](https://github.com/tinymce/tinymce) and compiled for the documentation site using [MoxieDoc](https://github.com/tinymce/moxiedoc). @@ -124,42 +75,6 @@ The TinyMCE API documentation is maintained within the [TinyMCE project reposito - [Node.js](https://nodejs.org/en/). - The TinyMCE documentation repository set up for development as described in [Installing Prerequisites](#installing-prerequisites) and [First time set up](#first-time-set-up). -##### Installing MoxieDoc - -To install MoxieDoc, run: - -``` -npm install -g git://github.com/tinymce/moxiedoc.git#feature/tinymcenext -``` - -##### Run the development version of the documentation for the current TinyMCE version - -1. Download the TinyMCE version in the `.api-version` file in this project's root directory and extract the API documentation using: -``` -./_scripts/api-reference.sh -``` - -2. Start the development server using: -``` -./_scripts/serve.sh -``` - -##### Run the development version of the documentation for a local TinyMCE repository - -1. Extract the API documentation from a local copy of the TinyMCE repository using: -``` -./_scripts/api-reference-local.sh -``` -2. Start the development server using: -``` -./_scripts/serve.sh -``` -3. To include updates made to the TinyMCE API documentation in the TinyMCE repository, run the `api-reference-local` script: -``` -./_scripts/api-reference-local.sh -``` - ->**Note**: The development server does not need to be stopped prior to running the `api-reference-local` script. ### Live Demos diff --git a/_scripts/api-reference-local.sh b/_scripts/api-reference-local.sh index 24ed12685..2520c45f6 100755 --- a/_scripts/api-reference-local.sh +++ b/_scripts/api-reference-local.sh @@ -17,6 +17,19 @@ mkdir "$API_TMPDIR" moxiedoc "$1/modules/tinymce/src/core/main/ts" -t antora -o "$API_TMPDIR/tinymce-api-reference.zip" unzip -o "$API_TMPDIR/tinymce-api-reference.zip" -sed -i "s;^- url: api;- url: apis;" _data/nav_api.yml +# remove old api adoc pages +rm -rf modules/root/pages/apis/ -echo "" \ No newline at end of file +# removed old static api html pages (clear cache), it can corrupt the build +rm -rf build/site/_/tinymce/6.0/apis/ + +# move newly generated adoc pages, antora will then generate new static html pages +mv _data/antora modules/root/pages/apis + +# move api navigation +mv _data/moxiedoc_nav.adoc modules/root/moxiedoc_nav.adoc + +# cleanup moxiedoc tmp _data folder +rm -rf _data + +echo "donesky - using local build of tinymce" \ No newline at end of file diff --git a/_scripts/api-reference.sh b/_scripts/api-reference.sh index 7af39fa60..8f9fcc1f3 100755 --- a/_scripts/api-reference.sh +++ b/_scripts/api-reference.sh @@ -2,7 +2,6 @@ set -e -# API_VERSION="$(cat .api-version)" API_VERSION="5.10.2" TARBALL_URL="https://codeload.github.com/tinymce/tinymce/tar.gz/$API_VERSION" API_TMPDIR="/tmp/tinymce-$API_VERSION" diff --git a/package.json b/package.json index 2b62e5166..02f93e567 100644 --- a/package.json +++ b/package.json @@ -10,7 +10,9 @@ "scripts": { "watch": "nodemon --exec antora antora-playbook.yml", "server": "http-server build/site/ --port 4000", - "serve": "npm-run-all -p watch server" + "serve": "npm-run-all -p watch server", + "build": "./_scripts/api-reference.sh", + "build-local": "./_scripts/api-reference-local.sh" }, "author": "Tiny Technologies Inc", "license": "CC-BY-NC-SA-3.0", @@ -31,6 +33,7 @@ "http-server": "^0.12.3", "liquidjs": "~9.25.0", "nodemon": "^2.0.7", - "npm-run-all": "^4.1.5" + "npm-run-all": "^4.1.5", + "moxiedoc": "git://github.com/tinymce/moxiedoc.git#feature/antora" } }