GitHub Pages Import
===================
[](https://github.com/davisp/ghp-import/actions?query=workflow%3Aci)
[](https://circleci.com/gh/c-w/ghp-import/tree/master)
[](https://travis-ci.org/c-w/ghp-import)
[](https://opensource.org/licenses/Apache-2.0)
[](https://pypi.org/project/ghp-import/)
As part of [gunicorn][gunicorn], [Benoit Chesneau][benoit] and [Paul Davis][davisp]
were looking at how to host documentation. There's the obvious method of
using [GitHub's post-receive hook][github-post] to trigger doc builds and rsync
to a webserver, but we ended up wanting to try out github's hosting to make the
whole interface a bit more robust.
[GitHub Pages][gh-pages] is a pretty awesome service that GitHub provides for
hosting project documentation. The only thing is that it requires a
`gh-pages` branch that is the site's document root. This means that keeping
documentation sources in the branch with code is a bit difficult. And it really
turns into a head scratcher for things like [Sphinx][sphinx] that want to
access documentation sources and code sources at the same time.
Then we stumbled across an interesting looking package called
[github-tools][github-tools] that looked almost like what we wanted. It was a tad
complicated and more involved than we wanted but it gave us an idea. Why not
just write a script that can copy a directory to the `gh-pages` branch of the
repository. This saves us from even having to think about the branch and
everything becomes magical.
This is what `ghp-import` was written for.
[gunicorn]: http://www.gunicorn.com/ "Gunicorn"
[benoit]: http://github.com/benoitc "Benoît Chesneau"
[davisp]: http://github.com/davisp "Paul J. Davis"
[github-post]: https://help.github.com/articles/post-receive-hooks "GitHub Post-Receive Hook"
[gh-pages]: http://pages.github.com/ "GitHub Pages"
[sphinx]: http://sphinx.pocoo.org/ "Sphinx Documentation"
[github-tools]: http://dinoboff.github.com/github-tools/ "github-tools"
Big Fat Warning
---------------
This will **DESTROY** your `gh-pages` branch. If you love it, you'll want to
take backups before playing with this. This script assumes that `gh-pages` is
100% derivative. You should never edit files in your `gh-pages` branch by hand
if you're using this script because you will lose your work.
When used with a prefix, only files below the set prefix will be destroyed, limiting the
above warning to just that directory and everything below it.
Usage
-----
```
Usage: ghp-import [OPTIONS] DIRECTORY
Options:
-n, --no-jekyll Include a .nojekyll file in the branch.
-c CNAME, --cname=CNAME
Write a CNAME file with the given CNAME.
-m MESG, --message=MESG
The commit message to use on the target branch.
-p, --push Push the branch to origin/{branch} after committing.
-x PREFIX, --prefix=PREFIX
The prefix to add to each file that gets pushed to the
remote. Only files below this prefix will be cleared
out. [none]
-f, --force Force the push to the repository.
-o, --no-history Force new commit without parent history.
-r REMOTE, --remote=REMOTE
The name of the remote to push to. [origin]
-b BRANCH, --branch=BRANCH
Name of the branch to write to. [gh-pages]
-s, --shell Use the shell when invoking Git. [False]
-l, --follow-links Follow symlinks when adding files. [False]
-h, --help show this help message and exit
```
Its pretty simple. Inside your repository just run `ghp-import $DOCS_DIR`
where `$DOCS_DIR` is the path to the **built** documentation. This will write a
commit to your `gh-pages` branch with the current documents in it.
If you specify `-p` it will also attempt to push the `gh-pages` branch to
GitHub. By default it'll just run `git push origin gh-pages`. You can specify
a different remote using the `-r` flag.
The `-o` option will discard any previous history and ensure that only a
single commit is always pushed to the `gh-pages` branch. This is useful to
avoid bloating the repository size and is **highly recommended**.
You can specify a different branch with `-b`. This is useful for user and
organization page, which are served from the `master` branch.
Some Windows users report needing to pass Git commands through the shell which can be accomplished by passing `-s`.
The `-l` option will cause the import to follow symlinks for users that have odd configurations that include symlinking outside of their documentation directory.
Python Usage
------------
You can also call ghp_import directly from your Python code as a library. The
library has one public function `ghp_import.ghp_import`, which accepts the
following arguments:
* `srcdir`: The path to the **built** documentation (required).
* `remote`: The name of the remote to push to. Default: `origin`.
* `branch`: Name of the branch to write to. Default: `gh-pages`.
* `mesg`: The commit message to use on the target branch. Default: `Update documentation`.
* `push`: Push the branch to {remote}/{branch} after committing. Default: `False`.
* `prefix`: The prefix to add to each file that gets pushed to the remote. Default: `None`.
* `force`: Force the push to the repository. Default: `False`.
* `no_history`: Force new commit without parent history. Default: `False`.
* `use_shell`: Default: Use the shell when invoking Git. `False`.
* `followlinks`: Follow symlinks when adding files. Default: `False`.
* `cname`: Write a CNAME file with the given CNAME. Default: `None`.
* `nojekyll`: Include a .nojekyll file in the branch. Default: `False`.
With Python's current working directory (cwd) inside your repository, do the
following:
```python
from ghp_import import ghp_import
ghp_import('docs', push=True, cname='example.com')
```
Raw data
{
"_id": null,
"home_page": "https://github.com/c-w/ghp-import",
"name": "ghp-import",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Paul Joseph Davis",
"author_email": "paul.joseph.davis@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d9/29/d40217cbe2f6b1359e00c6c307bb3fc876ba74068cbab3dde77f03ca0dc4/ghp-import-2.1.0.tar.gz",
"platform": null,
"description": "GitHub Pages Import\n===================\n\n[](https://github.com/davisp/ghp-import/actions?query=workflow%3Aci)\n[](https://circleci.com/gh/c-w/ghp-import/tree/master)\n[](https://travis-ci.org/c-w/ghp-import)\n\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://pypi.org/project/ghp-import/)\n\nAs part of [gunicorn][gunicorn], [Benoit Chesneau][benoit] and [Paul Davis][davisp]\nwere looking at how to host documentation. There's the obvious method of\nusing [GitHub's post-receive hook][github-post] to trigger doc builds and rsync\nto a webserver, but we ended up wanting to try out github's hosting to make the\nwhole interface a bit more robust.\n\n[GitHub Pages][gh-pages] is a pretty awesome service that GitHub provides for\nhosting project documentation. The only thing is that it requires a\n`gh-pages` branch that is the site's document root. This means that keeping\ndocumentation sources in the branch with code is a bit difficult. And it really\nturns into a head scratcher for things like [Sphinx][sphinx] that want to\naccess documentation sources and code sources at the same time.\n\nThen we stumbled across an interesting looking package called\n[github-tools][github-tools] that looked almost like what we wanted. It was a tad\ncomplicated and more involved than we wanted but it gave us an idea. Why not\njust write a script that can copy a directory to the `gh-pages` branch of the\nrepository. This saves us from even having to think about the branch and\neverything becomes magical.\n\nThis is what `ghp-import` was written for.\n\n[gunicorn]: http://www.gunicorn.com/ \"Gunicorn\"\n[benoit]: http://github.com/benoitc \"Beno\u00eet Chesneau\"\n[davisp]: http://github.com/davisp \"Paul J. Davis\"\n[github-post]: https://help.github.com/articles/post-receive-hooks \"GitHub Post-Receive Hook\"\n[gh-pages]: http://pages.github.com/ \"GitHub Pages\"\n[sphinx]: http://sphinx.pocoo.org/ \"Sphinx Documentation\"\n[github-tools]: http://dinoboff.github.com/github-tools/ \"github-tools\"\n\n\nBig Fat Warning\n---------------\n\nThis will **DESTROY** your `gh-pages` branch. If you love it, you'll want to\ntake backups before playing with this. This script assumes that `gh-pages` is\n100% derivative. You should never edit files in your `gh-pages` branch by hand\nif you're using this script because you will lose your work.\n\nWhen used with a prefix, only files below the set prefix will be destroyed, limiting the\nabove warning to just that directory and everything below it.\n\nUsage\n-----\n\n```\nUsage: ghp-import [OPTIONS] DIRECTORY\n\nOptions:\n -n, --no-jekyll Include a .nojekyll file in the branch.\n -c CNAME, --cname=CNAME\n Write a CNAME file with the given CNAME.\n -m MESG, --message=MESG\n The commit message to use on the target branch.\n -p, --push Push the branch to origin/{branch} after committing.\n -x PREFIX, --prefix=PREFIX\n The prefix to add to each file that gets pushed to the\n remote. Only files below this prefix will be cleared\n out. [none]\n -f, --force Force the push to the repository.\n -o, --no-history Force new commit without parent history.\n -r REMOTE, --remote=REMOTE\n The name of the remote to push to. [origin]\n -b BRANCH, --branch=BRANCH\n Name of the branch to write to. [gh-pages]\n -s, --shell Use the shell when invoking Git. [False]\n -l, --follow-links Follow symlinks when adding files. [False]\n -h, --help show this help message and exit\n```\n\nIts pretty simple. Inside your repository just run `ghp-import $DOCS_DIR`\nwhere `$DOCS_DIR` is the path to the **built** documentation. This will write a\ncommit to your `gh-pages` branch with the current documents in it.\n\nIf you specify `-p` it will also attempt to push the `gh-pages` branch to\nGitHub. By default it'll just run `git push origin gh-pages`. You can specify\na different remote using the `-r` flag.\n\nThe `-o` option will discard any previous history and ensure that only a\nsingle commit is always pushed to the `gh-pages` branch. This is useful to\navoid bloating the repository size and is **highly recommended**.\n\nYou can specify a different branch with `-b`. This is useful for user and\norganization page, which are served from the `master` branch.\n\nSome Windows users report needing to pass Git commands through the shell which can be accomplished by passing `-s`.\n\nThe `-l` option will cause the import to follow symlinks for users that have odd configurations that include symlinking outside of their documentation directory.\n\nPython Usage\n------------\n\nYou can also call ghp_import directly from your Python code as a library. The\nlibrary has one public function `ghp_import.ghp_import`, which accepts the\nfollowing arguments:\n\n* `srcdir`: The path to the **built** documentation (required).\n* `remote`: The name of the remote to push to. Default: `origin`.\n* `branch`: Name of the branch to write to. Default: `gh-pages`.\n* `mesg`: The commit message to use on the target branch. Default: `Update documentation`.\n* `push`: Push the branch to {remote}/{branch} after committing. Default: `False`.\n* `prefix`: The prefix to add to each file that gets pushed to the remote. Default: `None`.\n* `force`: Force the push to the repository. Default: `False`.\n* `no_history`: Force new commit without parent history. Default: `False`.\n* `use_shell`: Default: Use the shell when invoking Git. `False`.\n* `followlinks`: Follow symlinks when adding files. Default: `False`.\n* `cname`: Write a CNAME file with the given CNAME. Default: `None`.\n* `nojekyll`: Include a .nojekyll file in the branch. Default: `False`.\n\nWith Python's current working directory (cwd) inside your repository, do the\nfollowing:\n\n```python\nfrom ghp_import import ghp_import\nghp_import('docs', push=True, cname='example.com')\n```\n\n\n",
"bugtrack_url": null,
"license": "Apache Software License",
"summary": "Copy your docs directly to the gh-pages branch.",
"version": "2.1.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "0adbda2f4e8981b29e60b5d6b4e30183",
"sha256": "8337dd7b50877f163d4c0289bc1f1c7f127550241988d568c1db512c4324a619"
},
"downloads": -1,
"filename": "ghp_import-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0adbda2f4e8981b29e60b5d6b4e30183",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 11034,
"upload_time": "2022-05-02T15:47:14",
"upload_time_iso_8601": "2022-05-02T15:47:14.552377Z",
"url": "https://files.pythonhosted.org/packages/f7/ec/67fbef5d497f86283db54c22eec6f6140243aae73265799baaaa19cd17fb/ghp_import-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "1150fdae5997f1ae0d09df9d7f9e7df2",
"sha256": "9c535c4c61193c2df8871222567d7fd7e5014d835f97dc7b7439069e2413d343"
},
"downloads": -1,
"filename": "ghp-import-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "1150fdae5997f1ae0d09df9d7f9e7df2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 10943,
"upload_time": "2022-05-02T15:47:16",
"upload_time_iso_8601": "2022-05-02T15:47:16.110234Z",
"url": "https://files.pythonhosted.org/packages/d9/29/d40217cbe2f6b1359e00c6c307bb3fc876ba74068cbab3dde77f03ca0dc4/ghp-import-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-05-02 15:47:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "c-w",
"github_project": "ghp-import",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"circle": true,
"lcname": "ghp-import"
}
JSON
