Create greetings.yml

Create a greetings message to show users who submit their first Issue or first PR to the repo.

.github/workflows/check.yml

@@ -1,24 +0,0 @@
-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 pandoc
-        pip3 install --user -r requirements.txt
-    - name: Build the docs
-      run: |
-        export PATH="$HOME/.local/bin:$PATH"
-        make py
-        make man
-        make htmlall
-        

.github/workflows/greetings.yml

@@ -9,5 +9,5 @@ jobs:
     - 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.'
+        issue-message: 'Welcome to Clear Linux OS Docs. Thanks for submitting your first issue. :thumbsup:'
+        pr-message: 'Welcome to Clear Linux OS Docs. Thanks for submitting your first PR. :thumbsup:'

.github/workflows/linkcheck.yml

@@ -1,22 +0,0 @@
-name: Linkcheck
-
-on:
-  schedule:
-    - cron: '0 0 * * Mon,Wed,Fri'
-
-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: CheckLinks
-      run: |
-        export PATH="$HOME/.local/bin:$PATH"
-        make linkcheck

.github/workflows/main.yml

@@ -1,40 +0,0 @@
-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 pandoc
-        pip3 install --user -r requirements.txt
-    - name: Build the docs
-      run: |
-        export PATH="$HOME/.local/bin:$PATH"
-        make py
-        make man
-        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

@@ -1,44 +0,0 @@
-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 pandoc
-        pip3 install --user -r requirements.txt
-    - name: Build the docs
-      run: |
-        export PATH="$HOME/.local/bin:$PATH"
-        make py
-        make man
-        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

@@ -17,13 +17,3 @@ bundles.html.txt
 
 # ignore the venv, used for running make py
 venv
-
-#ignore for reDocs GUI
-.tox
-MANIFEST
-
-# ignore artifacts of man page generation
-source/_scripts/_python/manpages/*.rst
-source/reference/manpages
-source/_scripts/_python/manpages/*/
-source/reference/man-pages.rst

Makefile

@@ -25,12 +25,6 @@ linkcheck:
 py:
 	make -C source py
 
-man:
-	make -C source man
-
-clean-man:
-	make -C source clean-man
-
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html       to make standalone HTML files"
@@ -40,6 +34,7 @@ clean:
 	rm -rf venv
 
 venv:
-	virtualenv venv;\
+	virtualenv -p python$(PY_VERSION) venv;
 	source venv/bin/activate; \
 	pip3 install -r requirements.txt;
+

README.rst

@@ -63,95 +63,10 @@ running ``make html``:
 Open one of the HTML pages found in ``source/_build/html`` in a web browser
 to view the rendered documentation.
 
-This build will generate several warnings as there are two other optional make commands required to build the full documentation.
-
-1. ``make py`` to generate the bundle reference material.
-2. ``make man`` to generate man page reference material.
-
-To build the documentation exactly as seen on the website, use
-``make man``, ``make py``, and ``make htmlall``. This builds both
+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
 ***************
 
@@ -165,11 +80,7 @@ build before building again by running ``make clean``:
 
    make clean
 
-This will completely remove the previous build output, including artifacts 
-from the `make venv` target when done outside an active venv.
-
-Before running ``make man``, please run ``make clean-man`` to clear out any
-previous attempts.
+This will completely remove the previous build output.
 
 Convenience script
 ==================

make.bat

@@ -5,9 +5,7 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
-
-set SCRIPTDIR=source\_scripts\_python
-set BUILDDIR=source\_build
+set BUILDDIR=build
 set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source
 set I18NSPHINXOPTS=%SPHINXOPTS% source
 if NOT "%PAPER%" == "" (
@@ -32,7 +30,6 @@ if "%1" == "help" (
 	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
 	echo.  text       to make text files
 	echo.  man        to make manual pages
-	echo.  clean-man  to clean up after man page generation
 	echo.  texinfo    to make Texinfo files
 	echo.  gettext    to make PO message catalogs
 	echo.  changes    to make an overview over all changed/added/deprecated items
@@ -80,17 +77,6 @@ if "%1" == "html" (
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
-	copy source\_scripts\js\copybutton.js %BUILDDIR%\html\_static
-	goto end
-)
-
-if "%1" == "py" (
-	cd %SCRIPTDIR%
-	python.exe bundle_lister.py
-	copy bundles.html.txt ..\..\reference\bundles
-	for /d %%i in (cloned_repo\*) do rmdir /q /s %%i
-	del /q /s bundles.html.txt
-	echo "Python bundle script finished successfully!"
 	goto end
 )
 
@@ -200,14 +186,10 @@ if "%1" == "text" (
 )
 
 if "%1" == "man" (
-    cd source/_scripts/_python/manpages
-    man.bat man
-	goto end
-)
-
-if "%1" == "clean-man" (
-	cd source/_scripts/_python/manpages
-	man.bat clean-man
+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The manual pages are in %BUILDDIR%/man.
 	goto end
 )
 

requirements.txt

@@ -1,10 +1,8 @@
 breathe==4.9.1
-sphinx==2.2.0
+sphinx==1.8
 docutils==0.14
 sphinx_rtd_theme
 sphinx-intl==2.0.0
 sphinx-sitemap==1.0.2
-Jinja2==2.11.3
-GitPython==3.0.8
-sphinx-tabs
-sphinx-copybutton
+Jinja2==2.10.1
+GitPython==2.1.11

setup.py

@@ -1,11 +0,0 @@
-#!/usr/bin/env python
-
-from distutils.core import setup
-
-setup(name='Clear Linux Documentation',
-      version='',
-      description='Sphinx build of Clear Linux documentation',
-      author='Many',
-      author_email='kevin.putnam@intel.com',
-      url='https://github.com/clearlinux/clear-linux-documentation/',
-      )

source/FAQ/index.rst

@@ -12,17 +12,8 @@ Below is a list of commonly asked questions with answers sourced from the
 General
 *******
 
-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?
-===============================
+Why did you make another distro?
+================================
 
 The |CL| team felt that performance was left on the table with Linux software.
 |CL| takes a holistic approach to improve performance across the stack. We
@@ -30,23 +21,15 @@ also wanted to take more modern approaches with OS updates and tooling.
 
 |
 
-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|?
-=======================================
+Can other distros copy |CL| improvements?
+=========================================
 
 Yes, we absolutely love open source reuse and upstreaming improvements.
 
 |
 
-How often does it update?
-=========================
+How often do you update?
+========================
 
 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
@@ -60,16 +43,15 @@ 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:`telemetry <telem-guide>` guide for more information.
+:ref:`telem-guide` guide for more information.
 
 |
 
 What is the default firewall?
 =============================
 
-|CL| packages :command:`iptables` and :command:`firewalld` as optional
-bundles, however, there are no default firewall rules. All network traffic is
-allowed by default.
+|CL| packages :command:`iptables` as a bundle, however, there are no default
+firewall rules. All network traffic is allowed by default.
 
 |
 
@@ -78,35 +60,21 @@ 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/`.
-|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.
+Files under :file:`/etc/` are not created unless you create one.
 
+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
 
 |
 
-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
-********
+Software packages
+*****************
 
 How is software installed and updated?
 ======================================
 
-|CL| provides software in the form of :ref:`bundles <bundles-guide>` and
+|CL| provides software in the form of :ref:`bundles-guide` and
 updates software with :ref:`swupd <swupd-guide>`.
 
 :ref:`Flatpak\* <flatpak-tutorial>` is an application virtualization solution
@@ -118,29 +86,15 @@ bundles whenever possible.
 
 |
 
-Does it use RPMs or DEBs packages like other distros?
-=====================================================
+Does |CL| use RPMs like other distros?
+======================================
 
-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/>`_.
+|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.
 
+Individual RPMs can sometimes be manually installed on a |CL| system with the
+right tools, but that is not the intended use case.
 
 |
 
@@ -173,9 +127,8 @@ 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
-<https://github.com/clearlinux/distribution/issues/422>`_ can be found on
-GitHub.
+A discussion on manually installing and maintaining Google Chrome can be found
+on GitHub: https://github.com/clearlinux/distribution/issues/422
 
 |
 
@@ -189,17 +142,13 @@ the `software store`_. Installing Flatpak apps is also covered in our
 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?
 ====================
 
@@ -210,12 +159,13 @@ 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, 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>`_.
+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.
 
 |
 
@@ -226,8 +176,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 community contributed tutorial has been shared on how to :ref:`manually
-install ZFS <zfs>`.
+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

@@ -50,8 +50,6 @@ help:
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 	@echo "  coverage   to run coverage check of the documentation (if enabled)"
 	@echo "  py         to trigger an update of bundle content"
-	@echo "  man        to pull and create manpage rst files in reference section"
-	@echo "  clean-man  to clean up manpage generation"
 
 clean:
 	rm -rf $(BUILDDIR)/*
@@ -73,7 +71,6 @@ htmlzh:
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	cp _scripts/js/copybutton.js $(BUILDDIR)/html/_static
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
@@ -213,9 +210,3 @@ pseudoxml:
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
-
-man:
-	$(MAKE) -C $(SCRIPTDIR)/manpages man
-
-clean-man:
-	$(MAKE) -C $(SCRIPTDIR)/manpages clean-man