Merge branch 'development' of https://github.com/intelkevinputnam/clear-linux-documentation into development

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

.github/workflows/check.yml

@@ -0,0 +1,23 @@
+name: Check
+
+on: [pull_request]
+
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Install dependencies
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        sudo apt-get install -y python3-setuptools
+        pip3 install --user -r requirements.txt
+    - name: Build the docs
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        make py
+        make htmlall
+        

.github/workflows/greetings.yml

@@ -0,0 +1,13 @@
+name: Greetings
+
+on: [pull_request, issues]
+
+jobs:
+  greeting:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/first-interaction@v1
+      with:
+        repo-token: ${{ secrets.GITHUB_TOKEN }}
+        issue-message: 'Welcome to Clear Linux* OS Docs. Thanks for submitting your first issue.'
+        pr-message: 'Welcome to Clear Linux* OS Docs. Thanks for submitting your first PR.'

.github/workflows/main.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches:
+        - master
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Install dependencies
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        sudo apt-get install -y python3-setuptools
+        pip3 install --user -r requirements.txt
+    - name: Build the docs
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        make py
+        make htmlall
+    - name: Pre-deploy
+      run: |
+        wget https://github.com/clearlinux/clear-linux-documentation-zh-CN/releases/latest/download/clearlinux-docs-zh-CN.tar.gz
+        mkdir source/_build/html/zh_CN
+        tar xvzf clearlinux-docs-zh-CN.tar.gz -C source/_build/html/zh_CN
+        mv source/_build/html $HOME/output
+    - name: Deploy the docs
+      run: |
+        cd $HOME/output
+        git init
+        git config --global user.name "${GITHUB_ACTOR}"
+        git config --global user.email "${GITHUB_ACTOR}@github.com"
+        git add .
+        git commit -m "latest html output"
+        git push -f https://${GITHUB_ACTOR}:${{secrets.ACCESS_TOKEN}}@github.com/clearlinux/clear-linux-documentation.git HEAD:developmentHTML

.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish
+
+on:
+  push:
+    branches:
+        - publish
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Install dependencies
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        sudo apt-get install -y python3-setuptools
+        pip3 install --user -r requirements.txt
+    - name: Build the docs
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        make py
+        make htmlall
+    - name: Pre-deploy
+      run: |
+        wget https://github.com/clearlinux/clear-linux-documentation-zh-CN/releases/latest/download/clearlinux-docs-zh-CN.tar.gz
+        mkdir source/_build/html/zh_CN
+        tar xvzf clearlinux-docs-zh-CN.tar.gz -C source/_build/html/zh_CN
+        mv source/_build/html $HOME/output
+    - name: Deploy the docs
+      run: |
+        cd $HOME/output
+        git init
+        git config --global user.name "${GITHUB_ACTOR}"
+        git config --global user.email "${GITHUB_ACTOR}@github.com"
+        git add .
+        git commit -m "latest html output"
+        git push -f https://${GITHUB_ACTOR}:${{secrets.ACCESS_TOKEN}}@github.com/clearlinux/clear-linux-documentation.git HEAD:latestHTML
+    - name: Publish the docs
+      run: |
+        wget ${{secrets.PUBLISH_URL}}
+        cat clearlinux-latest

.gitignore

@@ -14,3 +14,6 @@ source/_build
 # ignore artifacts generated by running make py
 cloned_repo
 bundles.html.txt
+
+# ignore the venv, used for running make py
+venv

.travis.yml

@@ -1,37 +0,0 @@
-language: python
-
-python:
-  - "3.6"
-
-# command to install dependencies
-install: 
-  - pip3 install -q -r requirements.txt
-  - pip3 install -q -r source/_scripts/_python/requirements.txt
-
-# command to run tests
-script: 
-  - make py
-  - make htmlall
-
-before_deploy:
-  - make linkcheck
-
-deploy:
-  - provider: pages
-    skip_cleanup: true
-    github_token: $GITHUB_TOKEN
-    target-branch: latestHTML
-    on:
-      branch: master
-    local_dir: source/_build/html/
-  - provider: pages
-    skip_cleanup: true
-    github_token: $GITHUB_TOKEN
-    target-branch: developmentHTML
-    on:
-      branch: development
-    local_dir: source/_build/html/
-
-after_deploy:
-  - wget $PUBLISH_URL
-  - cat clearlinux-latest

Makefile

@@ -1,5 +1,8 @@
 # Makefile for Sphinx documentation
-#
+
+SHELL := /bin/bash
+
+PY_VERSION ?= 3.6
 
 all:
 	make -C source html
@@ -28,4 +31,9 @@ help:
 
 clean:
 	make -C source clean
+	rm -rf venv
 
+venv:
+	virtualenv venv;\
+	source venv/bin/activate; \
+	pip3 install -r requirements.txt;

README.rst

@@ -10,38 +10,46 @@ documentation locally for development and testing.
 Please make yourself familiar with our `contribution guidelines`_ before
 submitting a contribution.
 
-Requirements
-************
-
-Make sure you have Python and Sphinx installed. We use Python 3 and
-Sphinx 1.7.5
-
-The Sphinx documentation provides `instructions for installing Sphinx`_ on various
-platforms.
-
 Clone the documentation repository
 **********************************
 
-Once Sphinx is installed, clone the documentation repository to your
-local machine.
+Clone the documentation repository to your local machine.
 
-.. code-block:: console
+.. code-block:: bash
 
-   $ git clone https://github.com/clearlinux/clear-linux-documentation
+   git clone https://github.com/clearlinux/clear-linux-documentation
+
+Requirements
+************
+
+Make sure you have Python 3 installed to start.
+
+The Sphinx documentation provides `instructions for installing Sphinx`_
+on various platforms.
+
+Use pip3 to install additional Python dependencies listed in the
+requirements.txt file found in the repository:
+
+.. code-block:: bash
+
+   pip3 install -r requirements.txt
 
 Run the build
 *************
 
 We build our documentation using Sphinx. In the source directory of your
-local clear-linux-documentation repository, build the documentation by running
-**make html**:
+local clear-linux-documentation repository, preview changes to the
+documentation by building the docs in the default language (English) by
+running ``make html``:
+
+.. code-block:: bash
+
+   make html
 
 .. code-block:: console
 
-   $ make html
-   >
    sphinx-build -b html -d _build/doctrees   . _build/html
-   Running Sphinx v1.7.5
+   Running Sphinx v1.8.0
    making output directory...
    .
    .
@@ -52,23 +60,134 @@ local clear-linux-documentation repository, build the documentation by running
 
    Build finished. The HTML pages are in _build/html.
 
-Open one of the HTML pages in a web browser to view the rendered
-documentation.
+Open one of the HTML pages found in ``source/_build/html`` in a web browser
+to view the rendered documentation.
+
+If you want to build the documentation exactly as seen on the website, use
+``make py`` followed by ``make htmlall``. This builds some
+external dependencies and all supported languages.
+
+Use virtualenv 
+**************
+
+To develop documentation in a ``virtualenv``, use the ``venv`` target.
+The Clear Linux OS documentation make target ``venv`` provides a 
+simple development environment that ensures that you have the 
+latest packages and that you manage Python versions separately. Use of the 
+``virtualenv`` requires **Python 3.6** or higher. For Windows examples below, use Powershell as an Administrator.
+
+The **virtual environment** uses the same version of Python that was used to **create the virtual environment**. 
+
+Verify ``pip`` is installed. A file path to pip should appear. 
+
+On Clear Linux OS and macOS\*:
+
+.. code-block:: bash
+
+   which pip
+   
+On Windows\* 10 OS: 
+
+.. code-block:: bash
+
+   pip --version
+
+If ``pip`` is not installed, install it. 
+
+On Clear Linux OS and macOS:
+
+.. code-block:: bash
+
+   python3 -m pip install --user --upgrade pip
+
+On Windows 10 OS: 
+
+.. code-block:: bash
+
+   py -m pip install --upgrade pip
+
+.. note::
+
+   This assumes Python was already added to your Windows path. 
+
+Install virtualenv 
+==================
+
+Install ``virtualenv``. 
+
+On Clear Linux OS and macOS\*:
+
+.. code-block:: bash
+
+   python3 -m pip install --user virtualenv
+
+On Windows 10 OS: 
+
+.. code-block:: bash
+
+   py -m pip install --user virtualenv
+
+Create the ``virtualenv`` and install the required packages: 
+
+.. code-block:: bash
+
+   make venv
+
+Activate the ``venv``. 
+
+.. code-block:: bash
+
+   source venv/bin/activate
+
+Follow `Run the build`_ section to start developing documentation.
+
+Remove the ``venv`` when finished developing.  
+
+.. code-block:: bash
+
+   deactivate
+
+Additional help
+***************
+
+Cleaning up
+===========
 
 When testing changes in the documentation, make sure to remove the previous
-build before building again by running **make clean**:
+build before building again by running ``make clean``:
 
-.. code-block:: console
+.. code-block:: bash
+
+   make clean
+
+This will completely remove the previous build output, including artifacts 
+from the `make venv` target when done outside an active venv.
+
+Convenience script
+==================
+
+This bash script (Linux only) includes both ``make clean`` and
+``make html``. It also starts a simple Python web server that
+displays a preview of the site at http://localhost:8000 on your local machine.
+
+.. code-block:: bash
+
+   ./checkwork.sh
+
+To stop the web server simply use ``ctrl-c``.
+
+<<<<<<< HEAD
+
+### Silly header to test dev branch
 
-   $ make clean
-   >
-   rm -rf _build/*
 
-This will completely remove the previous build output.
 
 .. _Clear Linux\* OS documentation:  https://clearlinux.org/documentation
+=======
+.. _Clear Linux\* OS documentation:  https://docs.01.org/clearlinux/
+>>>>>>> 550b919bc013159156f80110867aa1ab7c858d29
 .. _Sphinx: http://sphinx-doc.org/
 .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
-.. _contribution guidelines: https://clearlinux.org/documentation/clear-linux/reference/collaboration
+.. _contribution guidelines: https://docs.01.org/clearlinux/latest/collaboration/collaboration.html
 .. _instructions for installing Sphinx: https://www.sphinx-doc.org/en/master/usage/installation.html
 

notravis.yml

@@ -0,0 +1,54 @@
+language: python
+
+python:
+  - "3.6"
+
+# command to install dependencies
+install:
+  - pip3 install -q -r requirements.txt
+
+# command to run tests
+script:
+  - make py
+  - make htmlall
+
+before_deploy:
+  - make linkcheck
+  # only deploy the latest tagged release of Simplified Chinese docs
+  - wget https://github.com/clearlinux/clear-linux-documentation-zh-CN/releases/latest/download/clearlinux-docs-zh-CN.tar.gz
+  - mkdir source/_build/html/zh_CN
+  - tar xvzf clearlinux-docs-zh-CN.tar.gz -C source/_build/html/zh_CN
+
+deploy:
+  - provider: pages
+    skip_cleanup: true
+    github_token: $GITHUB_TOKEN
+    target-branch: latestHTML
+    on:
+      branch: publish
+    local_dir: source/_build/html/
+  - provider: pages
+    skip_cleanup: true
+    github_token: $GITHUB_TOKEN
+    target-branch: developmentHTML
+    on:
+      branch: master
+    local_dir: source/_build/html/
+  - provider: pages
+    skip_cleanup: true
+    github_token: $GITHUB_TOKEN
+    target-branch: developmentHTML
+    on:
+      branch: development
+    local_dir: source/_build/html/
+  - provider: releases
+    skip_cleanup: true
+    api_key: $GITHUB_TOKEN
+    file: clearlinux-docs-zh-CN.tar.gz
+    on:
+      tags: true
+
+
+after_deploy:
+  - wget $PUBLISH_URL
+  - cat clearlinux-latest

requirements.txt

@@ -3,4 +3,7 @@ sphinx==1.8
 docutils==0.14
 sphinx_rtd_theme
 sphinx-intl==2.0.0
-sphinx-sitemap==1.0.2
+sphinx-sitemap==1.0.2
+Jinja2==2.10.1
+GitPython==3.0.8
+sphinx-tabs

source/FAQ/index.rst

@@ -12,26 +12,43 @@ Below is a list of commonly asked questions with answers sourced from the
 General
 *******
 
-Why did you make another distro?
-================================
+What is |CL|?
+=============
+
+|CL| is an open source, rolling release Linux distribution optimized for
+performance and security. See `the about page <https://clearlinux.org/about>`_
+for more information.
+
+|
+
+Why another Linux distribution?
+===============================
 
 The |CL| team felt that performance was left on the table with Linux software.
-|CL| takes a holistic approach to improving performance across the stack. We
+|CL| takes a holistic approach to improve performance across the stack. We
 also wanted to take more modern approaches with OS updates and tooling.
 
 |
 
-Can other distros copy |CL| improvements?
-=========================================
+Is it a derivative of another Linux distribution?
+=================================================
+
+No. |CL| is a new Linux distribution. It is not a fork and does not have a
+parent Linux distribution.
+
+|
+
+Can others copy improvements from |CL|?
+=======================================
 
 Yes, we absolutely love open source reuse and upstreaming improvements.
 
 |
 
-How often do you update?
-========================
+How often does it update?
+=========================
 
-The |CL| team puts out multiple releases a week, often releasing 2 or more
+The |CL| team puts out multiple releases a week, often releasing two or more
 times a day. This rolling release approach allows |CL| to remain agile to
 upstream changes and security patches.
 
@@ -43,15 +60,16 @@ Is telemetry required?
 The telemetry solution provided by |CL| is entirely optional and customizable.
 It is disabled by default. If you do choose to enable telemetry, the data
 helps the |CL| team proactively identify and resolve bugs. See the
-:ref:`telem-guide` guide for more information.
+:ref:`telemetry <telem-guide>` guide for more information.
 
 |
 
 What is the default firewall?
 =============================
 
-|CL| packages :command:`iptables` as a bundle, however, there are no default
-firewall rules. All network traffic is allowed by default.
+|CL| packages :command:`iptables` and :command:`firewalld` as optional
+bundles, however, there are no default firewall rules. All network traffic is
+allowed by default.
 
 |
 
@@ -60,21 +78,35 @@ Where are the files that I usually see under /etc like fstab?
 
 |CL| has a stateless design that maintains a separation between system files
 and user files. Default values are stored under :file:`/usr/share/defaults/`.
-Files under :file:`/etc/` are not created unless you create one.
+|CL| starts with a mostly empty :file:`/etc` directory to store user-defined
+configurations. See the :ref:`stateless <stateless>` page for more information.
+
+See `this blog post
+<https://clearlinux.org/news-blogs/where-etcfstab-clear-linux>`_ for an
+example explaining how this is accomplished with :file:`/etc/fstab/`
+specifically.
 
-A blog post explaining how this is accomplished with :file:`/etc/fstab/`
-specifically is available here:
-https://clearlinux.org/news-blogs/where-etcfstab-clear-linux
 
 |
 
-Software packages
-*****************
+Does it use the Intel Compiler (icc)?
+=====================================
+
+No. |CL| uses open source compilers: :command:`gcc` and :command:`clang`. |CL|
+does not compile any packages with :command:`icc`. 
+
+For a more detailed explanation, see `this discussion on the community forum
+<https://community.clearlinux.org/t/does-clear-linux-os-use-the-intel-compiler-icc-tl-nope/>`_.
+
+|
+
+Software
+********
 
 How is software installed and updated?
 ======================================
 
-|CL| provides software in the form of :ref:`bundles-guide` and
+|CL| provides software in the form of :ref:`bundles <bundles-guide>` and
 updates software with :ref:`swupd <swupd-guide>`.
 
 :ref:`Flatpak\* <flatpak-tutorial>` is an application virtualization solution
@@ -86,15 +118,29 @@ bundles whenever possible.
 
 |
 
-Does |CL| use RPMs like other distros?
-======================================
+Does it use RPMs or DEBs packages like other distros?
+=====================================================
 
-|CL| provides software in the form of :ref:`bundles-guide`. The RPM
-format is used as an intermediary step for packaging and determining software
-dependencies at OS build time.
+No. |CL| provides software to systems in the form of :ref:`bundles-guide`.
+Under the hood, |CL| developers use the RPM format as an intermediary step for
+packaging and determining software dependencies at OS build time.
+
+Individual RPMs and DEBs can sometimes be manually extracted and installed on
+a |CL| system with the right tools, but that is not the intended use case.
+
+|
+
+Why does it have a different approach to software management?
+=============================================================
+
+The |CL| team wants software *installation* and *updates* to be as efficient
+and error free as possible. |CL| packages software differently and uses a
+novel updater to solve some of the classic problems with how the software
+packages are on Linux. 
+
+For a more detailed explanation, see `this discussion on our community forum
+<https://community.clearlinux.org/t/why-does-clearlinux-use-swupd-and-not-apt-deb-rpm/>`_.
 
-Individual RPMs can sometimes be manually installed on a |CL| system with the
-right tools, but that is not the intended use case.
 
 |
 
@@ -127,8 +173,9 @@ Is Google\* Chrome\* available?
 The Google Chrome web browser is not distributed as a bundle in |CL| due to
 copyright and licensing complexities.
 
-A discussion on manually installing and maintaining Google Chrome can be found
-on GitHub: https://github.com/clearlinux/distribution/issues/422
+A `discussion on manually installing and maintaining Google Chrome
+<https://github.com/clearlinux/distribution/issues/422>`_ can be found on
+GitHub.
 
 |
 
@@ -137,18 +184,22 @@ Is Microsoft\* Visual Studio Code\* available?
 
 Yes. Find the CLI command for installing `VS Code`_ and other Flatpak apps in
 the `software store`_. Installing Flatpak apps is also covered in our
-:ref:`tutorial <flatpak-tutorial>`. 
+:ref:`tutorial <flatpak-tutorial>`.
 
 The |CL| team is working on a natively packaged version of Visual Studio Code
 for future release.
 
-Join a community forum discussion about manually installing and maintaining
-Visual Studio Code: https://community.clearlinux.org/t/need-native-support-for-vs-code-through-swupd/
+Join a community `forum discussion about manually installing and maintaining
+Visual Studio Code
+<https://community.clearlinux.org/t/need-native-support-for-vs-code-through-swupd/>`_.
+
 
 .. _VS Code: https://clearlinux.org/software?search_api_fulltext=vscode
 
 |
 
+.. _licensing_restrict:
+
 Is FFmpeg available?
 ====================
 
@@ -159,13 +210,12 @@ various media encoding/decoding, streaming, and playback.
 complexities (See https://www.ffmpeg.org/legal.html and
 http://blog.pkh.me/p/13-the-ffmpeg-libav-situation.html).
 
-Read more in the |CL| repository, including discussion of an alternative
-hardware-based solution:
-https://github.com/clearlinux/distribution/issues/429.
 
-While |CL| cannot distribute FFmpeg, a manual solution to build and install
-FFmpeg under :file:`/usr/local` has been shared on the community forums:
-https://community.clearlinux.org/t/how-to-h264-etc-support-for-firefox-including-ffmpeg-install.
+While |CL| cannot distribute FFmpeg, solutions for manually building and
+installing FFmpeg have been shared by users `on GitHub
+<https://github.com/clearlinux/distribution/issues/429>`_ and `the community
+forums
+<https://community.clearlinux.org/t/how-to-h264-etc-support-for-firefox-including-ffmpeg-install>`_.
 
 |
 
@@ -176,8 +226,8 @@ ZFS is not available with |CL| because of copyright and licensing
 complexities. BTRFS is an alternative filesystem that is available in |CL|
 natively.
 
-A user on GitHub notes that the ZFS kernel module can be compiled, built, and
-installed manually: https://github.com/clearlinux/distribution/issues/631
+A user on GitHub notes that the `ZFS kernel module can be compiled, built, and
+installed manually <https://github.com/clearlinux/distribution/issues/631>`_.
 
 |
 

source/Makefile

@@ -53,10 +53,11 @@ help:
 
 clean:
 	rm -rf $(BUILDDIR)/*
+	rm -rf reference/bundles/*.txt
 
-htmlall: 
+htmlall:
 	$(SPHINXBUILD) -b html $(ERROROPTS) $(ALLSPHINXOPTS) $(BUILDDIR)/html	
-	$(SPHINXBUILD) -b html $(ERROROPTS) -D language='zh_CN' $(ALLSPHINXOPTS) $(BUILDDIR)/html/zh_CN 
+	$(SPHINXBUILD) -b html $(ERROROPTS) -D language='zh_CN' $(ALLSPHINXOPTS) $(BUILDDIR)/zh_CN 
 
 htmlde:
 	$(SPHINXBUILD) -b html -D language='de' $(ALLSPHINXOPTS) $(BUILDDIR)/html/de