{"id":22058884,"url":"https://github.com/teracyhq/sphinx-deployment","last_synced_at":"2025-05-12T19:42:55.910Z","repository":{"id":71225176,"uuid":"12181884","full_name":"teracyhq/sphinx-deployment","owner":"teracyhq","description":"automatic setup and deployment for sphinx docs","archived":false,"fork":false,"pushed_at":"2019-03-01T06:40:22.000Z","size":56,"stargazers_count":26,"open_issues_count":1,"forks_count":8,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-01T02:48:31.126Z","etag":null,"topics":["gh-pages","github-page","heroku","rsync","shell","sphinx","sphinx-deployment","sphinx-doc"],"latest_commit_sha":null,"homepage":"http://blog.teracy.com/tags/sphinx-deployment/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/teracyhq.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2013-08-17T16:35:37.000Z","updated_at":"2020-05-25T12:29:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"d659bc94-ce8b-491b-b1b9-2df9626a4f82","html_url":"https://github.com/teracyhq/sphinx-deployment","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teracyhq%2Fsphinx-deployment","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teracyhq%2Fsphinx-deployment/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teracyhq%2Fsphinx-deployment/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teracyhq%2Fsphinx-deployment/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/teracyhq","download_url":"https://codeload.github.com/teracyhq/sphinx-deployment/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253809588,"owners_count":21967755,"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":["gh-pages","github-page","heroku","rsync","shell","sphinx","sphinx-deployment","sphinx-doc"],"created_at":"2024-11-30T17:25:57.872Z","updated_at":"2025-05-12T19:42:55.899Z","avatar_url":"https://github.com/teracyhq.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"sphinx-deployment\n=================\n\nAutomatic setup and deployment for [sphinx][] docs.\n\nThis project is intended to be used to deploy [sphinx][] project on:\n\n- [Github Pages](https://help.github.com/categories/20/articles)\n- [Rsync](http://en.wikipedia.org/wiki/Rsync)\n- PaaS services: [heroku](http://heroku.com/), etc.\n\nUsage\n-----\n\n**1. `$ make generate`**\n\nFor generating contents, alias for `$ make html`\n\n**2. `$ make deploy`**\n\nFor short-cut deployment, it could be `$ make deploy_gh_pages`, `$ make deploy_rsync` or\n`$ make deploy_heroku` basing on the configuration of `DEPLOY_DEFAULT`.\n\n**3. `$ make gen_deploy`**\n\nFor short-cut generation and deployment: `$ make generate` and then `$ make deploy`.\n\n**4. `$ make setup_gh_pages`**\n\nFor the first time only to create `$(DEPLOY_DIR)` to track `$(DEPLOY_BRANCH)`. This is used for\ngithub pages deployment.\n\n**5. `$ make setup_heroku`**\n\nFor the first time only to create `$(DEPLOY_DIR_HEROKU` to track the Heroku repo's master branch.\nThis is used for heroku deployment.\n\n**6. `$ make deploy_gh_pages`**\n\nFor deploying with github pages only.\n\n**7. `$ make deploy_rsync`**\n\nFor deploying with rsync only.\n\n**8. `$ make deploy_heroku`**\n\nFor deploying with heroku only.\n\n**9. `$ make livehtml`**\n\nFor auto-building the documentation when a change is detected thanks to https://pypi.org/project/sphinx-autobuild/\n\n**10. `$ make build_docker_image`**\n\nTo build the production docker image for the docs site, for example:\n\n```\n$ make build_docker_image DOCKER_IMG_TAG=company/project-docs:develop\n```\n\n\nInstallation\n------------\n\n**1. Bash script**\n\nJust run this bash script from your root git repository project and it's enough.\n\nYou need to specify the `\u003cdocs_path\u003e` to your sphinx docs directory:\n\n``` bash\n$ cd \u003cyour_project\u003e\n$ wget https://raw.githubusercontent.com/teracyhq/sphinx-deployment/master/scripts/spxd.sh \u0026\u0026 chmod +x ./spxd.sh \u0026\u0026 ./spxd.sh -p \u003cdocs_path\u003e\n```\n\nFor example:\n\n``` bash\n$ cd my_project\n$ wget https://raw.githubusercontent.com/teracyhq/sphinx-deployment/master/scripts/spxd.sh \u0026\u0026 chmod +x ./spxd.sh \u0026\u0026 ./spxd.sh -p ./docs\n```\n\n**2. Manual**\n\na. You need to copy these following files to your [sphinx][] directory:\n\n- `docs/requirements`\n- `docs/sphinx_deployment.mk`\n- `docs/rsync_exclude`\n- `docs/.deploy_heroku/*`\n- `docs/.gitignore`\n\nb. Include `sphinx_deployment.mk` to your `Makefile`:\n\n- Add the content below to your `Makefile`:\n\n```\ninclude sphinx_deployment.mk\n```\n\n- Or do with commands on terminal:\n\n``` bash\necho '' \u003e\u003e Makefile\necho 'include sphinx_deployment.mk' \u003e\u003e Makefile\n```\n\n\nc.. To build with `travis-ci`, you need to copy these following files to your root project directory:\n\n- `.travis.yml`\n- `.travis/setup.sh`\n\n\nAuto-build with docker-compose\n------------------------------\n\nMake sure `docker` and `docker-compose` are installed and running.\n\n```bash\n$ docker-compose up -d\n$ echo open http://localhost:`docker port docs_docs_1 80 | grep -o [0-9]*$` to view the docs\nopen http://localhost:32770 to view the docs\n```\n\nCheck the output from the command above to open the docs site. The docs site will auto reload when\nchanges are made to the docs files.\n\nTo see the docs site logs, execute the following command:\n\n```bash\n$ docker-compose logs -f docs\n```\n\n\nConfiguration\n-------------\n\nYou need to configure these following deployment configurations following your project settings on\n`sphinx_deployment.mk` file.\n\n``` Makefile\n# Deployment configurations from sphinx_deployment project\n\n# default deployment when $ make deploy\n# deploy_gh_pages                            : to $ make deploy_gh_pages\n# deploy_rsync                               : to $ make deploy_rsync\n# deploy_heroku                              : to $ make deploy_heroku\n# deploy_gh_pages deploy_rsync deploy_heroku : to $ make deploy_gh_pages then $ make deploy_rsync\n#                                              and then $ make deploy_heroku\n# default value: deploy_gh_pages\nifndef DEPLOY_DEFAULT\nDEPLOY_DEFAULT = deploy_gh_pages\nendif\n\n# The deployment directory to be deployed\nifndef DEPLOY_DIR\nDEPLOY_DIR      = _deploy\nendif\n\n# The heroku deployment directory to be deployed\n# we must create this separated dir to avoid any conflict with _deploy (rsync and gh_pages)\nifndef DEPLOY_DIR_HEROKU\nDEPLOY_DIR_HEROKU = _deploy_heroku\nendif\n\n# Copy contents from $(BUILDDIR) to $(DEPLOY_DIR)/$(DEPLOY_HTML_DIR) directory\nifndef DEPLOY_HTML_DIR\nDEPLOY_HTML_DIR = docs\nendif\n\n\n## -- Rsync Deploy config -- ##\n# Be sure your public key is listed in your server's ~/.ssh/authorized_keys file\nifndef SSH_USER\nSSH_USER       = user@domain.com\nendif\n\nifndef SSH_PORT\nSSH_PORT       = 22\nendif\n\nifndef DOCUMENT_ROOT\nDOCUMENT_ROOT  = ~/website.com/\nendif\n\n#If you choose to delete on sync, rsync will create a 1:1 match\nifndef RSYNC_DELETE\nRSYNC_DELETE   = false\nendif\n\n# Any extra arguments to pass to rsync\nifndef RSYNC_ARGS\nRSYNC_ARGS     =\nendif\n\n## -- Github Pages Deploy config -- ##\n\n# Configure the right deployment branch\nifndef DEPLOY_BRANCH_GITHUB\nDEPLOY_BRANCH_GITHUB = gh-pages\nendif\n\n#if REPO_URL_GITHUB was NOT defined by travis-ci\nifndef REPO_URL_GITHUB\n# Configure your right github project repo\n# REPO_URL       = git@github.com:teracy-official/sphinx-deployment.git\nendif\n\n## -- Heroku Deployment Config -- ##\n\nifndef REPO_URL_HEROKU\n# Configure your right heroku repo\n# REPO_URL_HEROKU = git@heroku.com:spxd.git\nendif\n\n## -- Docker Config -- ##\n\nifndef DOCKER_IMG_TAG\n# Configure your default docker image tag\nDOCKER_IMG_TAG = sphinx-deployment/docs:develop\nendif\n\n## end deployment configuration, don't edit anything below this line ##\n#######################################################################\n```\n\nContinuous Integration Build\n----------------------------\n\n**1. `travis-ci`**\n\nMove `.travis.yml` file to your root repository project, and configure it following its\ninstruction there. There is a supported `.travis/setup.sh` to export variables for `Makefile`\ndepending on the being-built branch.\n\nTo configure secure token for `travis-ci`, please read the similar step described at\nhttp://blog.teracy.com/2013/08/03/how-to-start-blogging-easily-with-octopress-and-teracy-dev/\n\n\n**2. `jenkins`**\n\n//TODO\n\n\nAuthors and contributors\n------------------------\n\n- Hoat Le: http://github.com/hoatle\n\n- Many thanks to http://octopress.org/docs/deploying/ for inspiration.\n\nLicense\n-------\n\nBSD License\n\n```\nCopyright (c) Teracy, Inc. and individual contributors.\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without modification,\nare permitted provided that the following conditions are met:\n\n    1. Redistributions of source code must retain the above copyright notice,\n       this list of conditions and the following disclaimer.\n\n    2. Redistributions in binary form must reproduce the above copyright\n       notice, this list of conditions and the following disclaimer in the\n       documentation and/or other materials provided with the distribution.\n\n    3. Neither the name of Teracy, Inc. nor the names of its contributors may be used\n       to endorse or promote products derived from this software without\n       specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND\nANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED\nWARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\nDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR\nANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\n(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;\nLOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON\nANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\n(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS\nSOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n```\n\n[sphinx]: http://sphinx-doc.org\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteracyhq%2Fsphinx-deployment","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fteracyhq%2Fsphinx-deployment","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteracyhq%2Fsphinx-deployment/lists"}