first commit

.gitignore

@@ -0,0 +1,17 @@
+
+*.log
+
+# Python
+
+__pycache__/
+*.pyc
+.hypothesis
+.pytest_cache
+*.py[cod]
+*$py.class
+*.so
+
+# Ide
+.vscode
+
+

Dockerfile

@@ -0,0 +1,18 @@
+
+#QUICK TESTS START
+#FROM python:3-alpine
+#NOTE: there no apk in readthedocs
+#RUN apk --no-cache add git make
+#QUICK TESTS END
+
+FROM readthedocs/build:6.0
+
+ADD entrypoint.sh /entrypoint.sh
+
+# we need to override RTD 'docs' user:
+# https://github.com/readthedocs/readthedocs-docker-images/blob/master/Dockerfile#L136
+# because of this:
+#https://help.github.com/en/actions/reference/virtual-environments-for-github-hosted-runners#docker-container-filesystem
+USER root
+
+ENTRYPOINT ["/entrypoint.sh"]

LICENSE.txt

@@ -0,0 +1,14 @@
+
+   Copyright 2020 David Leoni
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -0,0 +1,22 @@
+
+# ReadTheDocs to Github Actions
+
+Sphinx docs build using the same Docker and environment of ReadTheDocs server.
+
+**Might be suitable when you need to:**
+
+- migrate from ReadTheDocs
+- build (possibly complex) PDFs and epubs using maintained RTD Dockerfile 
+- support multiple versions and languages
+- have locally reproducible build
+
+**STATUS**: it's my first Github Actions attempt so you will probably need to adapt it to your own needs, especially when it comes to multiple versions and languages. See [issues](https://github.com/DavidLeoni/readthedocs-to-actions/issues)
+
+The approach is a bit heavyweight (RTD docker alone is at least 5 gigas), so you may well want to try [other fine solutions for Sphinx](https://github.com/ammaraskar/sphinx-action) 
+
+## Technical description
+
+Tries to mimic RTD build process in [entrypoint.sh](entrypoint.sh) using RTD Dockerfile Ubuntu configuration, and if used as Github Action, Sphinx `_build` output is made available in `/github/workspace` which is shared by steps in a Github Action job.
+
+Dockerfile is also usable locally for your own builds.
+

action.yml

@@ -0,0 +1,39 @@
+# action.yml
+name: 'Sphinx Docs build with ReadTheDocs Docker Image'
+description: 'entrypoint.sh tries to mimic RTD build process using RTD Dockerfile, and if used as Github Action Sphinx _build output is made available in /github/workspace. Dockerfile is also usable locally for your own builds.'
+inputs:
+  rtd-prj-name: 
+    description: |
+      ReadTheDocs project name - also used as name for pdfs and epubs. 
+      NOTE: you don't need to actually have a project on readthedocs servers!    
+    default: 'myproject'
+    required: true
+  git-url:
+    description: 'Full git url to clone the repo'
+    required: true
+  git-tag:
+    description: 'tag or branch'    
+    default: master
+    required: false
+  version:
+    description: 'version as named on the website'    
+    default: latest  
+    required: false
+  requirements: 
+    description: 'requirements file for pip install'    
+    default: 'requirements.txt'
+  language: 
+    description: 'Documentation language'    
+    default: 'en'
+    required: false
+runs:
+  using: 'docker'
+  image: 'Dockerfile'
+  args:
+    - ${{ inputs.rtd-prj-name }}
+    - ${{ inputs.git-url }}
+    - ${{ inputs.git-tag }}
+    - ${{ inputs.version }}
+    - ${{ inputs.requirements }}
+    - ${{ inputs.language }}
+

entrypoint.sh

@@ -0,0 +1,94 @@
+#!/bin/sh
+set -o errexit #abort if any command fails
+set -x
+
+# NOTE: you don't need to actually have a project on readthedocs servers!
+RTD_PRJ_NAME=$1  # 'jupman', also used as name for pdfs and epubs
+GIT_URL=$2       # https://github.com/DavidLeoni/jupman.git
+GIT_TAG=$3       # tag or branch, i.e.  master
+VERSION=$4       # latest
+REQUIREMENTS=$5  # requirements.txt
+LANGUAGE=$6      # en
+
+RTD_PRJ_PATH=/home/docs/checkouts/readthedocs.org/user_builds/$RTD_PRJ_NAME
+
+echo "using   RTD_PRJ_NAME=$RTD_PRJ_NAME"
+echo "using   GIT_URL=$GIT_URL"
+echo "using   GIT_TAG=$GIT_TAG"
+echo "using   VERSION=$VERSION"
+echo "using   REQUIREMENTS=$REQUIREMENTS"
+echo "using   LANGUAGE=$LANGUAGE"
+echo
+echo "using   RTD_PRJ_PATH=$RTD_PRJ_PATH"
+
+# Reproduce build of ReadTheDocs --- START
+
+# MANUALLY ADDED !
+mkdir -p $RTD_PRJ_PATH/checkouts/$VERSION/
+# MANUALLY ADDED !
+mkdir -p $RTD_PRJ_PATH/artifacts/$VERSION/sphinx_pdf
+# MANUALLY ADDED !
+mkdir -p $RTD_PRJ_PATH/artifacts/$VERSION/sphinx_epub
+
+# MANUALLY ADDED !
+cd $RTD_PRJ_PATH/checkouts/$VERSION
+
+
+git clone --no-single-branch --depth 50 $GIT_URL . 
+
+git checkout --force origin/$GIT_TAG 
+
+git clean -d -f -f
+
+python3.7 -mvirtualenv  $RTD_PRJ_PATH/envs/$VERSION 
+
+$RTD_PRJ_PATH/envs/$VERSION/bin/python -m pip install --upgrade --no-cache-dir pip
+
+
+# modded to add quotes for < so shell doesn't complain
+$RTD_PRJ_PATH/envs/$VERSION/bin/python -m pip install --upgrade --no-cache-dir Pygments==2.3.1 setuptools==41.0.1 docutils==0.14 mock==1.0.1 pillow==5.4.1 "alabaster>=0.7,<0.8,!=0.7.5" commonmark==0.8.1 recommonmark==0.5.0 "sphinx<2" "sphinx-rtd-theme<0.5" "readthedocs-sphinx-ext<1.1"
+
+
+$RTD_PRJ_PATH/envs/$VERSION/bin/python -m pip install --exists-action=w --no-cache-dir -r $REQUIREMENTS
+
+cat conf.py
+
+#NOTE: in original log line is prepended by 'python '
+$RTD_PRJ_PATH/envs/$VERSION/bin/sphinx-build -T -E -b readthedocs -d _build/doctrees-readthedocs -D language=$LANGUAGE . _build/html 
+
+#NOTE: in original log line is prepended by 'python '
+$RTD_PRJ_PATH/envs/$VERSION/bin/sphinx-build -T -b readthedocssinglehtmllocalmedia -d _build/doctrees-readthedocssinglehtmllocalmedia -D language=$LANGUAGE . _build/localmedia
+
+#NOTE: in original log line is prepended by 'python '
+$RTD_PRJ_PATH/envs/$VERSION/bin/sphinx-build -b latex -D language=$LANGUAGE -d _build/doctrees . _build/latex
+
+#NOTE: MANUALLY ADDED !
+cd ./_build/latex/
+
+cat latexmkrc
+
+latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=$RTD_PRJ_NAME -interaction=nonstopmode 
+
+#NOTE: using cp instead of mv
+cp -f $RTD_PRJ_PATH/checkouts/$VERSION/./_build/latex/$RTD_PRJ_NAME.pdf $RTD_PRJ_PATH/artifacts/$VERSION/sphinx_pdf/$RTD_PRJ_NAME.pdf
+
+#NOTE: MANUALLY ADDED !
+cd $RTD_PRJ_PATH/checkouts/$VERSION
+
+#NOTE: in original log line is prepended by 'python '
+$RTD_PRJ_PATH/envs/$VERSION/bin/sphinx-build -T -b epub -d _build/doctrees-epub -D language=$LANGUAGE . _build/epub
+
+#NOTE: using cp instead of mv
+cp -f $RTD_PRJ_PATH/checkouts/$VERSION/./_build/epub/$RTD_PRJ_NAME.epub $RTD_PRJ_PATH/artifacts/$VERSION/sphinx_epub/$RTD_PRJ_NAME.epub 
+
+# Reproduce build of ReadTheDocs  -- END
+
+# MANUALLY ADDED !
+zip _build/$RTD_PRJ_NAME-html-$LANGUAGE-$VERSION.zip _build/html
+
+# MANUALLY ADDED !
+if [ -d "/github/workspace" ]; then  
+  echo "Extra: Found Github Actions environment, moving _build content to /github/workspace/"    
+  mv _build/* /github/workspace
+
+fi