Update to Accellera Documentation Flow (ADF)

CHANGELOG.md

@@ -3,3 +3,7 @@
 ## 2024-3-14
 
 * Clean-up as part of Accellera Style Guide
+
+## 2024-11-21
+
+* Separate Accellera Documentation Flow from documentation sources

Dockerfile

@@ -0,0 +1,115 @@
+# Dockerfile to create a ready-to-use docker image containing
+# the Accelllera Documentation Flow using the Electric Book templates
+
+FROM ubuntu:22.04
+
+# Main dependency installation
+RUN apt-get update && apt-get install -y \
+  software-properties-common \
+  make \
+  gcc \
+  build-essential \
+  git \
+  wget \
+  libgif7 \
+  libpixman-1-0 \
+  libffi-dev \
+  libreadline-dev \
+  zlib1g-dev \
+  graphicsmagick \
+  ruby-full
+
+# Dependencies specifically for Puppeteer on unix
+#RUN apt-get install -y \
+#  libasound2 \
+#  libatk1.0-0 \
+#  libatk-bridge2.0-0 \
+#  libcairo2 \
+#  libdrm2 \
+#  libgbm1 \
+#  libnss3 \
+#  libpango-1.0-0 \
+#  libxkbcommon-x11-0 \
+#  libxcomposite1 \
+#  libxdamage1 \
+#  libxfixes3 \
+#  libxrandr2
+
+# Install Microsoft Core Fonts
+RUN echo ttf-mscorefonts-installer msttcorefonts/accepted-mscorefonts-eula select true | debconf-set-selections
+RUN apt-get install ttf-mscorefonts-installer -y
+
+# Add node source for new nodejs, instead of old Ubuntu-installed node.
+# https://github.com/nodesource/distributions/wiki/How-to-migrate-to-the-new-repository
+
+# Update local package index
+RUN apt-get update
+# Install necessary packages for downloading and verifying new repository information
+RUN apt-get install -y ca-certificates curl gnupg
+# Create a directory for the new repository's keyring, if it doesn't exist
+RUN mkdir -p /etc/apt/keyrings
+# Download the new repository's GPG key and save it in the keyring directory
+RUN curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
+# Add the new repository's source list with its GPG key for package verification
+# Note: `node_20` means Node version 20. Update in future as needed.
+RUN echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list
+# Update local package index to recognize the new repository
+RUN apt-get update
+# Install Node.js from the new repository
+RUN apt-get install -y nodejs
+
+# Install program to configure locales
+RUN apt-get install -y locales
+RUN dpkg-reconfigure locales && \
+  locale-gen C.UTF-8 && \
+  /usr/sbin/update-locale LANG=C.UTF-8
+
+# Set default locale for the environment
+ENV LC_ALL C.UTF-8
+ENV LANG en_US.UTF-8
+ENV LANGUAGE en_US.UTF-8
+
+# Clear apt cache to make image smaller
+RUN apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/*
+
+# Install libssl1.1
+RUN wget http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.0g-2ubuntu4_amd64.deb && \
+  dpkg -i libssl1.1_1.1.0g-2ubuntu4_amd64.deb
+
+# Install PrinceXML for printing to PDF
+#RUN wget https://www.princexml.com/download/prince_11.4-1_ubuntu18.04_amd64.deb && \
+#  dpkg -i prince_11.4-1_ubuntu18.04_amd64.deb
+
+# Install pandoc for document conversion
+#RUN wget https://github.com/jgm/pandoc/releases/download/2.5/pandoc-2.5-1-amd64.deb && \
+#  dpkg -i pandoc-2.5-1-amd64.deb
+
+# Update npm
+RUN npm install -g npm@latest
+
+# Install Gulp cli app
+RUN npm install --global gulp-cli
+
+# Install bundler and jekyll
+RUN gem install jekyll bundler
+
+# Install gems.
+COPY Gemfile .
+RUN bash -lc "bundle install"
+
+# Switch to the user account
+RUN useradd -ms /bin/bash adf
+USER adf
+WORKDIR /home/adf
+
+# Set paths for Ruby gems
+RUN echo '# Define Ruby Gems path' >> ~/.bashrc
+RUN echo 'export GEM_HOME="$HOME/.rvm/gems/ruby-2.7.6"' >> ~/.bashrc
+RUN echo 'export PATH="$HOME/.rvm/gems/ruby-2.7.6:$PATH"' >> ~/.bashrc
+RUN bash -lc "source ~/.bashrc"
+
+# Copy all flow elements to container
+COPY --chown=adf:adf . .
+
+# Install Accellera Documentation Flow
+RUN npm install

Dockerfile.nocert

@@ -0,0 +1,118 @@
+# Dockerfile.nocert to create a ready-to-use docker image containing
+# the Accelllera Documentation Flow using the Electric Book templates
+# WARNING: This installation will disable TLS certificate checking
+# and could lead tp security issues. Instead use the Dockerfile
+
+FROM ubuntu:22.04
+
+# Main dependency installation
+RUN apt-get update && apt-get install -y \
+  software-properties-common \
+  make \
+  gcc \
+  build-essential \
+  git \
+  wget \
+  libgif7 \
+  libpixman-1-0 \
+  libffi-dev \
+  libreadline-dev \
+  zlib1g-dev \
+  graphicsmagick \
+  ruby-full
+
+# Dependencies specifically for Puppeteer on unix
+#RUN apt-get install -y \
+#  libasound2 \
+#  libatk1.0-0 \
+#  libatk-bridge2.0-0 \
+#  libcairo2 \
+#  libdrm2 \
+#  libgbm1 \
+#  libnss3 \
+#  libpango-1.0-0 \
+#  libxkbcommon-x11-0 \
+#  libxcomposite1 \
+#  libxdamage1 \
+#  libxfixes3 \
+#  libxrandr2
+
+# Install Microsoft Core Fonts
+RUN echo ttf-mscorefonts-installer msttcorefonts/accepted-mscorefonts-eula select true | debconf-set-selections
+RUN apt-get install ttf-mscorefonts-installer -y
+
+# Add node source for new nodejs, instead of old Ubuntu-installed node.
+# https://github.com/nodesource/distributions/wiki/How-to-migrate-to-the-new-repository
+
+# Update local package index
+RUN apt-get update
+# Install necessary packages for downloading and verifying new repository information
+RUN apt-get install -y ca-certificates curl gnupg
+# Create a directory for the new repository's keyring, if it doesn't exist
+RUN mkdir -p /etc/apt/keyrings
+# Download the new repository's GPG key and save it in the keyring directory
+RUN curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
+# Add the new repository's source list with its GPG key for package verification
+# Note: `node_20` means Node version 20. Update in future as needed.
+RUN echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list
+# Update local package index to recognize the new repository
+RUN apt-get update
+# Install Node.js from the new repository
+RUN apt-get install -y nodejs
+
+# Install program to configure locales
+RUN apt-get install -y locales
+RUN dpkg-reconfigure locales && \
+  locale-gen C.UTF-8 && \
+  /usr/sbin/update-locale LANG=C.UTF-8
+
+# Set default locale for the environment
+ENV LC_ALL C.UTF-8
+ENV LANG en_US.UTF-8
+ENV LANGUAGE en_US.UTF-8
+
+# Clear apt cache to make image smaller
+RUN apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/*
+
+# Install libssl1.1
+RUN wget http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.0g-2ubuntu4_amd64.deb && \
+  dpkg -i libssl1.1_1.1.0g-2ubuntu4_amd64.deb
+
+# Install PrinceXML for printing to PDF
+#RUN wget https://www.princexml.com/download/prince_11.4-1_ubuntu18.04_amd64.deb --no-check-certificate && \
+#  dpkg -i prince_11.4-1_ubuntu18.04_amd64.deb
+
+# Install pandoc for document conversion
+#RUN wget https://github.com/jgm/pandoc/releases/download/2.5/pandoc-2.5-1-amd64.deb --no-check-certificate && \
+#  dpkg -i pandoc-2.5-1-amd64.deb
+
+# Update npm
+RUN npm install -g npm@latest
+
+# Install Gulp cli app
+RUN npm install --global gulp-cli
+
+# Install bundler and jekyll
+RUN gem install jekyll bundler
+
+# Install gems.
+COPY Gemfile .
+RUN bash -lc "bundle install"
+
+# Switch to the user account
+RUN useradd -ms /bin/bash adf
+USER adf
+WORKDIR /home/adf
+
+# Set paths for Ruby gems
+RUN echo '# Define Ruby Gems path' >> ~/.bashrc
+RUN echo 'export GEM_HOME="$HOME/.rvm/gems/ruby-2.7.6"' >> ~/.bashrc
+RUN echo 'export PATH="$HOME/.rvm/gems/ruby-2.7.6:$PATH"' >> ~/.bashrc
+RUN bash -lc "source ~/.bashrc"
+
+# Copy all flow elements to container
+COPY --chown=adf:adf . .
+
+# Install Accellera Documentation Flow
+ENV NODE_TLS_REJECT_UNAUTHORIZED=0 
+RUN npm install

README.md

@@ -1,17 +1,25 @@
-# Accellera Style Guide
+# Accellera Documentation Flow (ADF)
 
-## Document generation
+The Accellera Documentation Flow offers the infrastructure to develop and publish Accellera (Draft) Standards, User Guides and other standard-related documentation. The main output are high-quality documents in Portable Document Format (PDF) compliant with the IEEE SA Standards Style Manual. Future extensions of this flow will also render interactive browser-compatible standards in HTML format. 
 
-To render the Accellera Style Guide, use the following command:
+The documentation flow is documented in the Accellera Style Guide, which explains the Markdown formatting and styles to create IEEE SA Standards compliant documents.
+
+## Usage
+
+The document sources shall be located in directory `books/<standard-document>/`.
+
+The document metadata (e.g. properties) shall be located in directory `_data/works/<standard-document>/`.
+
+To render a PDF document using the Accellera Documentation Flow, use the following command:
 
 ```sh
-npm run eb -- output --format screen-pdf --book accellera-style-guide
+$ npm run eb -- output --format screen-pdf --book <standard-document>
 ```
 
-It will generate a PDF in the `_output` directory.
+It will generate a PDF document in the `_output` directory.
 
-Please contact the Technical Committee chair in case of questions on the Accellera documentation flow, the required installation procedure or use of the standard document templates.
+Please contact the Technical Committee Chair in case of questions on the Accellera Documentation Flow, the required installation procedure or use of the standard document templates.
 
 ## Acknowledgment
 
-Special thanks to [Electric Book Works](https://electricbookworks.com/) for the development and support of this technical documentation flow.
+Special thanks to [Electric Book Works](https://electricbookworks.com/) for the development and support of the Accellera Documentation Flow.

_config.yml

@@ -37,7 +37,7 @@ canonical-url: "https://electricbookworks.github.io"
 # the name of your repo, e.g. /electric-book
 # It must start with a slash. Otherwise you can leave it blank. See:
 # http://downtothewire.io/2015/08/15/configuring-jekyll-for-user-and-project-github-pages/
-baseurl: "/accellera-style-guide"
+baseurl: ""
 
 # GitHub Pages repository
 # -----------------------
@@ -113,6 +113,9 @@ exclude:
   - package-lock.json
   - CNAME
   - .sass-cache
+  - Docker*
+  - netlify.toml
+  - setup.sh
 
   # Included as-is in other files, no need to process
   - /assets/js/annotation.js
@@ -148,6 +151,7 @@ exclude:
 
   # Files for formats we're not building here
   - /assets/profiles
+  - /books/*
   - /*/package.opf
   - /*/toc.ncx
   - /*/images/print-pdf

_configs/_config.app.yml

@@ -35,6 +35,9 @@ exclude:
   - package-lock.json
   - CNAME
   - .sass-cache
+  - Docker*
+  - netlify.toml
+  - setup.sh
 
   # Included as-is in other files, no need to process
   - /assets/js/annotation.js
@@ -87,3 +90,5 @@ exclude:
   - /*/styles/screen-pdf*
   - /*/styles/web*
   - /*/styles/epub*
+  - /books/*
+

_configs/_config.epub.yml

@@ -24,6 +24,9 @@ exclude:
   - package.json
   - package-lock.json
   - CNAME
+  - Docker*
+  - netlify.toml
+  - setup.sh
 
   # Included as-is in other files, no need to process
   - /assets/js/annotation.js
@@ -73,6 +76,7 @@ exclude:
   - /*/images/screen-pdf
   - /*/images/web
   - /*/images/app
+  - /books/*
 
   # Temporarily exclude book files for faster builds
   # - assets

_configs/_config.live.yml

@@ -31,6 +31,9 @@ exclude:
   - eslint.json
   - CHANGELOG.md
   - /*/images/source
+  - Docker*
+  - netlify.toml
+  - setup.sh
 
   # Included as-is in other files, no need to process
   - /assets/js/annotation.js
@@ -84,6 +87,7 @@ exclude:
   - /*/styles/app*
   - /*/package.opf
   - /*/toc.ncx
+  - /books/*
 
   # Exclude web images only if you keep_files them below
   # - /*/images/web

_configs/_config.print-pdf.yml

@@ -25,6 +25,9 @@ exclude:
   - package-lock.json
   - CNAME
   - .sass-cache
+  - Docker*
+  - netlify.toml
+  - setup.sh
 
   # Included as-is in other files, no need to process
   - /assets/js/annotation.js
@@ -91,6 +94,7 @@ exclude:
   - /*/images/web
   - /*/images/epub
   - /*/images/app
+  - /books/*
 
 # Temporarily exclude these and keep_files them below
 # for faster builds where you don't need to refresh these.

_configs/_config.screen-pdf.yml

@@ -25,6 +25,9 @@ exclude:
   - package-lock.json
   - CNAME
   - .sass-cache
+  - Docker*
+  - netlify.toml
+  - setup.sh
 
   # Included as-is in other files, no need to process
   - /assets/js/annotation.js
@@ -91,6 +94,7 @@ exclude:
   - /*/images/web
   - /*/images/epub
   - /*/images/app
+  - /books/*
 
 # Temporarily exclude these and keep_files them below
 # for faster builds where you don't need to refresh these.