{"id":18123303,"url":"https://github.com/jay-johnson/docker-sphinx-bootstrap","last_synced_at":"2025-04-06T12:45:34.057Z","repository":{"id":72596179,"uuid":"61929927","full_name":"jay-johnson/docker-sphinx-bootstrap","owner":"jay-johnson","description":"A containerized version of ryan-roemer's sphinx-bootstrap-theme repository so that on startup it will convert any rst files mounted from a host volume directory into themed, mobile-ready html.","archived":false,"fork":false,"pushed_at":"2016-06-27T17:17:39.000Z","size":33,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-12T18:49:58.774Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jay-johnson.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-06-25T06:19:27.000Z","updated_at":"2018-11-08T22:23:52.000Z","dependencies_parsed_at":"2023-05-24T15:15:28.700Z","dependency_job_id":null,"html_url":"https://github.com/jay-johnson/docker-sphinx-bootstrap","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jay-johnson%2Fdocker-sphinx-bootstrap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jay-johnson%2Fdocker-sphinx-bootstrap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jay-johnson%2Fdocker-sphinx-bootstrap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jay-johnson%2Fdocker-sphinx-bootstrap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jay-johnson","download_url":"https://codeload.github.com/jay-johnson/docker-sphinx-bootstrap/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247485253,"owners_count":20946398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-01T07:09:10.611Z","updated_at":"2025-04-06T12:45:34.027Z","avatar_url":"https://github.com/jay-johnson.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"=========================\nDocker + Sphinx Bootstrap\n=========================\n\nI built this repository_ for hosting my technical blog + resume + work portfolio. I containerized the sphinx-bootstrap_ repository so that on startup it will convert any ``rst`` files mounted from a host volume directory into themed, mobile-ready html. \n\nI use this repository for hosting and rendering ``rst`` as html on my blog:\n\nhttp://jaypjohnson.com\n\nDocker Hub Image: `jayjohnson/sphinx-bootstrap`_\n\nDate: **2016-06-24**\n\n.. role:: bash(code)\n      :language: bash\n\nOverview\n--------\n\nThis project started because I wanted to write content and not worry about formatting. When the container starts it converts `reStructuredText Markup`_ ``rst`` files into readable, static html. It does this by using the `python Sphinx bootstrap`_ documentation generator built from `Sphinx`_ + `bootstrap`_. Once containerized, I could focus my time on content (like this post). As a fan of data-driven products, I added configurable integration points for `Google Analytics`_ and `Google Search Console`_. I like that out-of-the-box the sphinx-bootstrap-theme_ comes with support for `multiple bootswatch themes`_ and there are even more themes available from the `bootswatch repository`_ and `bootswatch website`_. Additionally it creates well-formatted, mobile-ready blost posts and web pages. \n\nIntegrating with Google Analytics\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n1. Set your `Google Analytics Tracking Code`_ to the ENV_GOOGLE_ANALYTICS_CODE_ environment variable before container creation\n\n   During container startup the environment variable ``ENV_GOOGLE_ANALYTICS_CODE`` will be `automatically installed into the default html layout`_ on every page across your site\n\nIntegrating with Google Search Console\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n1. Automatic **sitemap.xml** creation\n\n   When the container starts or you `manually rebuild the html content`_ it will `automatically build`_ a ``sitemap.xml`` from any files ending with a ``.rst`` extension in the repository's root directory. This file is stored in the environment variable ``ENV_DOC_OUTPUT_DIR`` directory. This is handy when you want to integrate your site into the `Google Search Console`_ and it should look similar to: http://jaypjohnson.com/sitemap.xml\n\n.. _reStructuredText Markup: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html\n.. _python Sphinx bootstrap: https://github.com/ryan-roemer/sphinx-bootstrap-theme\n.. _Sphinx: http://www.sphinx-doc.org/en/stable/\n.. _sphinx-bootstrap-theme: https://github.com/ryan-roemer/sphinx-bootstrap-theme\n.. _Google Analytics: https://analytics.google.com/\n.. _Google Search Console: https://www.google.com/webmasters/tools/\n.. _multiple bootswatch themes: https://github.com/ryan-roemer/sphinx-bootstrap-theme/blob/bfb28af310ad5082fae01dc1ff08dab6ab3fa410/demo/source/conf.py#L146-L150\n.. _bootswatch website: http://bootswatch.com/\n.. _bootswatch repository: https://github.com/thomaspark/bootswatch\n.. _bootstrap: http://getbootstrap.com/\n.. _docker compose: https://docs.docker.com/compose/\n.. _manually rebuild the html content: https://github.com/jay-johnson/docker-sphinx-bootstrap/blob/2a752b96a7bcd378dbb207da1922c2e8997dc7ae/containerfiles/start-container.sh#L16-L17\n.. _automatically build: https://github.com/jay-johnson/docker-sphinx-bootstrap/blob/2a752b96a7bcd378dbb207da1922c2e8997dc7ae/containerfiles/start-container.sh#L21-L41\n.. _my blog: http://jaypjohnson.com\n.. _jayjohnson/sphinx-bootstrap: https://hub.docker.com/r/jayjohnson/sphinx-bootstrap/\n.. _Google Analytics Tracking Code: https://support.google.com/analytics/answer/1008080?hl=en\n.. _ENV_GOOGLE_ANALYTICS_CODE: https://github.com/jay-johnson/docker-sphinx-bootstrap/blob/2a752b96a7bcd378dbb207da1922c2e8997dc7ae/Dockerfile#L47\n.. _automatically installed into the default html layout: https://github.com/jay-johnson/docker-sphinx-bootstrap/blob/2a752b96a7bcd378dbb207da1922c2e8997dc7ae/containerfiles/start-container.sh#L13-L14\n\nGetting Started\n---------------\n\nBy default this container assumes there is a `sphinx-ready source`_ directory in ``/opt/blog/repo/``\n\nBuilding\n~~~~~~~~\n\nTo build the container you can run ``build.sh`` that automatically sources the properties.sh_ file:\n\n::\n\n    $ ./build.sh \n    Building new Docker image(docker.io/jayjohnson/sphinx-bootstrap)\n    Sending build context to Docker daemon 48.64 kB\n    Step 1 : FROM centos:7\n     ---\u003e 904d6c400333\n\n    ...\n\n    Removing intermediate container 4381745389cb\n    Successfully built 724130d8b97f\n    $\n\nHere is the full command:\n\n::\n    \n    docker build --rm -t \u003cyour name\u003e/sphinx-bootstrap --build-arg registry=docker.io --build-arg maintainer=\u003cyour name\u003e --build-arg imagename=sphinx-bootstrap .\n\n\nStart the Container\n~~~~~~~~~~~~~~~~~~~\n\nTo start the container run:\n\n::\n\n    $ ./start.sh \n    Starting new Docker image(docker.io/jayjohnson/sphinx-bootstrap)\n    d321c432272cc61de3270ef302ef2f269610d70238274479bda711ef9d11c564\n    $ \n\nLooking into the start.sh_ you can see that there are a few defaults taken from the properties.sh_ file:\n\n::\n\n    $ cat start.sh \n    #!/bin/bash\n\n    source ./properties.sh .\n\n    echo \"Starting new Docker image($registry/$maintainer/$imagename)\"\n    docker run --name=$imagename -v /opt/blog:/opt/blog -d $maintainer/$imagename \n\n    exit 0\n    $\n\n\nTest the Container\n~~~~~~~~~~~~~~~~~~\n\n#. Check the container is running with:\n\n   ::\n    \n       $ docker ps\n       CONTAINER ID        IMAGE                         COMMAND                  CREATED             STATUS              PORTS               NAMES\n       d321c432272c        jayjohnson/sphinx-bootstrap   \"/root/containerfiles\"   9 minutes ago       Up 9 minutes                            sphinx-bootstrap\n       $\n\n\n#. If the container started and generated the html correctly there should be a ``sitemap.xml`` file:\n\n   ::\n\n       $ ls /opt/blog/repo/release/sitemap.xml \n       /opt/blog/repo/release/sitemap.xml\n       $\n   \n\nEnvironment Variables\n~~~~~~~~~~~~~~~~~~~~~\n\nIf you are looking to configure the composition and containers, here are the available environment variables used by the containers:\n\n+----------------------------------------+--------------------------------------------------------------------+-------------------------------------------------------------+ \n| Variable Name                          | Purpose                                                            | Default Value                                               | \n+========================================+====================================================================+=============================================================+ \n| **ENV_DEFAULT_ROOT_VOLUME**            | Path to shared volume for static html, js, css, images, and assets | /opt/blog                                                   | \n+----------------------------------------+--------------------------------------------------------------------+-------------------------------------------------------------+ \n| **ENV_DOC_SOURCE_DIR**                 | Input directory where Sphinx processes ``rst`` files               | /opt/blog/repo/source                                       | \n+----------------------------------------+--------------------------------------------------------------------+-------------------------------------------------------------+ \n| **ENV_DOC_OUTPUT_DIR**                 | Output directory where Sphinx will output the ``html`` files       | /opt/blog/repo/release                                      | \n+----------------------------------------+--------------------------------------------------------------------+-------------------------------------------------------------+ \n| **ENV_BASE_DOMAIN**                    | Your web domain like: ``http://jayjohnson.com``                    | http://jaypjohnson.com                                      | \n+----------------------------------------+--------------------------------------------------------------------+-------------------------------------------------------------+ \n| **ENV_GOOGLE_ANALYTICS_CODE**          | Your Google Analytics Tracking Code like: ``UA-79840762-99``       | UA-79840762-99                                              | \n+----------------------------------------+--------------------------------------------------------------------+-------------------------------------------------------------+ \n\n\nWant to add a new blog post?\n----------------------------\n\n#. Open a new ``new-post.rst`` file in the ``source`` directory\n\n#. Add the following lines to the new ``new-post.rst`` file:\n\n   ::\n\n       ==================\n       This is a New Post\n       ==================\n   \n       My first blog post\n\n\n#. Edit the ``index.rst`` file and find the ``Site Contents`` section\n\n#. Add a new line to ``Site Contents`` **toctree** section containing: ``new-post`` \n\n   Here is how mine looks after adding it to the ``index.rst``\n\n   ::\n\n       Site Contents\n       -------------\n\n       .. toctree::\n           :maxdepth: 2\n   \n           new-post\n           python\n           work-history\n           contact\n           about\n\n\n   .. note:: One nice feature of the sphinx framework is it will automatically label the dropdown link with the first **Title** section found inside the file.\n\n#. Save the ``index.rst`` file\n\n#. Deploy and Rebuild the html files\n\n   Inside the ``websphinx`` container I included a `deploy + rebuild script`_ you can run from outside the container with:\n\n   ::\n\n       $ docker exec -it websphinx /root/containerfiles/deploy-new-content.sh\n\n#. Test the new post shows up in the site\n\n   ::\n\n       $ curl -s http://localhost:80/ | grep href | grep toctree | grep \"New Post\"\n       \u003cli class=\"toctree-l1\"\u003e\u003ca class=\"reference internal\" href=\"new-post.html\"\u003eThis is a New Post\u003c/a\u003e\u003c/li\u003e\n       \u003cli class=\"toctree-l1\"\u003e\u003ca class=\"reference internal\" href=\"new-post.html\"\u003eThis is a New Post\u003c/a\u003e\u003c/li\u003e\n       $\n\nRebuilding HTML content without restarting the docker container\n---------------------------------------------------------------\n\nI added a rebuild-html.sh_ script that handles converting the ``rst`` files into html without a container restart. To rebuild the content for a new revision or deployment just run:\n\n::\n\n     $ ./rebuild-html.sh \n     Rebuilding HTML with command: /root/containerfiles/deploy-new-content.sh\n     Done rebuilding html\n     $ \n\nStop the Container\n~~~~~~~~~~~~~~~~~~\n\nTo stop the container run:\n\n::\n\n    $ ./stop.sh \n    Stopping Docker image(docker.io/jayjohnson/sphinx-bootstrap)\n    sphinx-bootstrap\n    $ \n\nOr run the command:\n\n::\n    \n    docker stop sphinx-bootstrap\n\n\nLicenses\n--------\n\nThis repository is licensed under the MIT license.\n\nSphinx Bootstrap Theme is licensed under the MIT license.\n\nBootstrap v2 is licensed under the Apache license 2.0.\n\nBootstrap v3.1.0+ is licensed under the MIT license.\n\n\n.. _repository: https://github.com/jay-johnson/docker-sphinx-bootstrap\n.. _sphinx-bootstrap: https://hub.docker.com/r/jayjohnson/sphinx-bootstrap\n.. _start.sh: https://github.com/jay-johnson/docker-sphinx-bootstrap/blob/master/start.sh\n.. _start_container.sh: https://github.com/jay-johnson/docker-sphinx-bootstrap/blob/master/containerfiles/start-container.sh\n.. _properties.sh: https://github.com/jay-johnson/docker-sphinx-bootstrap/blob/master/properties.sh\n.. _sphinx-ready source: https://github.com/ryan-roemer/sphinx-bootstrap-theme/tree/master/demo\n.. _rebuild-html.sh: https://github.com/jay-johnson/docker-sphinx-bootstrap/blob/master/rebuild-html.sh\n.. _deploy + rebuild script: https://github.com/jay-johnson/docker-sphinx-bootstrap/blob/2a752b96a7bcd378dbb207da1922c2e8997dc7ae/containerfiles/deploy-new-content.sh\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjay-johnson%2Fdocker-sphinx-bootstrap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjay-johnson%2Fdocker-sphinx-bootstrap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjay-johnson%2Fdocker-sphinx-bootstrap/lists"}