diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..dfbde7c --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +docs/build diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..365aa98 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,11 @@ +FROM python:alpine +RUN pip install --upgrade pip +LABEL version="1.0.3" maintainer="rskntroot@gmail.com" + +RUN apk add --no-cache \ + make \ + py3-sphinx +RUN pip install myst-parser pydata-sphinx-theme + +WORKDIR /opt/sphinx + diff --git a/README.md b/README.md index 41c733c..ac3e6ea 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,9 @@ -# sphinx -Sphinx-Docs for Markdown on Alpine +# rskio sphinx-docs + +rskio website using sphinx-docs w/ markdown support on alpine-linux dockerized + +## Setup + +``` +docker compose up -d +``` diff --git a/bin/entrypoint.sh b/bin/entrypoint.sh new file mode 100755 index 0000000..d2db205 --- /dev/null +++ b/bin/entrypoint.sh @@ -0,0 +1,2 @@ +#!/bin/sh +make html diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..69e6971 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,21 @@ +version: "3.8" + +services: + sphinx-docs: + image: rskio/sphinx-docs + build: . + volumes: + - ./docs/:/opt/sphinx/ + - ./bin/entrypoint.sh:/opt/entrypoint.sh + entrypoint: /opt/entrypoint.sh + + nginx: + image: nginx:latest + ports: + - 9999:80 + volumes: + - ./docs/build/html:/opt/sphinx/html/:ro + - ./nginx/etc/conf.d/:/etc/nginx/conf.d/:ro + depends_on: + sphinx-docs: + condition: service_completed_successfully diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..d87f05e --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,28 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'Rskio' +copyright = '2024, rskntroot' +author = 'rskntroot' +release = '1.0.0' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +# Markdown Support - https://www.sphinx-doc.org/en/master/usage/markdown.html +extensions = ['myst_parser'] + +templates_path = ['_templates'] +exclude_patterns = [] + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +# PyData Theme - https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html (0.15.3) +html_theme = "pydata_sphinx_theme" +html_static_path = ['_static'] diff --git a/docs/source/docs/example.md b/docs/source/docs/example.md new file mode 100644 index 0000000..c346964 --- /dev/null +++ b/docs/source/docs/example.md @@ -0,0 +1,40 @@ +# Example + +## This is an Example Markdown File + +### sphinx-docs + +Sphinx Docs can be described as "website as code" similar to "infrastructure as code". + +Currently, this site is built out with the following components: + +``` +docker: + img: python:alpine +os: + apk: py3-sphinx +python: + pip: + - myst-parser + - pydata-sphinx-theme +``` + +Sphinx is used generate the html for site which can then be hosted separately: + +Generate Command: +``` +make html +``` + +Hosting: +``` +docker: + img: nginx:latest +``` + +#### Testing + +``` +cd /opt/docker +docker run -it --rm -v ./docs/build/html:/opt/sphinx/html/:ro -v ./nginx/etc/conf.d/:/etc/nginx/conf.d/:ro -p 9999:80 nginx:latest +``` diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..2562637 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,21 @@ +.. Rskio documentation master file, created by + sphinx-quickstart on Wed May 29 05:30:27 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Rskio +===== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + ./docs/example.md + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/nginx/etc/conf.d/default.conf b/nginx/etc/conf.d/default.conf new file mode 100644 index 0000000..82c9619 --- /dev/null +++ b/nginx/etc/conf.d/default.conf @@ -0,0 +1,22 @@ +server { + listen 80; + listen [::]:80; + server_name localhost rskio.com; + + # rskio logging is handled via traefik + #access_log /var/log/nginx/host.access.log main; + + location / { + root /opt/sphinx/html; + index index.html index.htm; + } + + # rskio auth is handled via traefik + #error_page 404 /404.html; + + error_page 500 502 503 504 /50x.html; + location = /50x.html { + root /usr/share/nginx/html; + } +} +