gh-publisher

This is a small package of software which will help you configure an automated build and publish process, using Travis CI and GitHub Pages.

gh-publisher was originally designed for academic and scientific papers written in LaTeX. Each change to the LaTeX triggers an automated build to re-generate the PDF and then publish it. You can easily extend gh-publisher to perform different build processes, as described below.

The publishing template is also configured to receive feedback on your work through GitHub Issues.

This is entirely dependent on GitHub and Travis CI.

Example here. Click through to the project on github to see the files in place.

Installation

I assume that you have a git repository of your own, containing whatever project it is that you want to build. If you haven't already done so, you need to host that repository on GitHub, and you need a local clone of it on your machine. If you don't know how to do that, see https://help.github.com.

The instructions below use the following references. Substitute the correct value whenever you see one of these:

  1. $PROJECT_DIR: the directory containing your local clone of your project.
  2. $GITHUB_USERNAME: your GitHub username.
  3. $REPO_NAME: the name of your project's git repository.

Enable issue tracking on GitHub

  1. Visit your repository settings at https://github.com/$GITHUB_USERNAME/$REPO_NAME/settings.
  2. In the Features section, ensure that Issues is checked.

Enable automated builds on Travis CI

  1. Sign in to Travis CI using your GitHub credentials at https://travis-ci.org.
  2. Visit your Travis CI profile page at https://travis-ci.org/profile/$GITHUB_USERNAME.
  3. Click Sync now to refresh the list of repositories.
  4. Enable builds on your repository by flicking the appropriate switch.

Allow Travis CI to publish to GitHub Pages on your behalf

You need to generate a GitHub access token. You are going to give this to Travis CI, which will grant it access to publish on your behalf.

  1. Visit your GitHub application settings at https://github.com/settings/applications.
  2. Under Personal access tokens, click "Generate new token". GitHub will ask for your password if you haven't entered it recently.
  3. Set the Token description to "Travis CI" (or whatever you want).
  4. Check "public_repo" as the scope, and uncheck all the other scopes. This limits Travis CI so that it is only able to publish to your public GitHub repositories, and can't modify anything else.
  5. Click Generate token.
  6. You will see a new token -- a long string of numbers and letters. Leave this window open for now -- this is the only time that you will see this token.
  7. In a new window, visit https://travis-ci.org/$GITHUB_USERNAME/$REPO_NAME/settings/env_vars.
  8. Click "Add a new variable".
  9. Set the Name to GH_TOKEN.
  10. Set the Value to that long string of numbers and letters in the other window.
  11. Leave "Display value in build logs" turned off.
  12. Click "Add".
  13. You can close the window with your GitHub access token now, you're done.

Configure the name and email address used on git commits

You can optionally set the name and email address used on the git commits when pages are published. If you don't do this, they will come out as "Automated build by gh-publisher <not.a.real.person@example.com>".

  1. Visit https://travis-ci.org/$GITHUB_USERNAME/$REPO_NAME/settings/env_vars.
  2. Click "Add a new variable".
  3. Set the Name to GIT_NAME.
  4. Set the Value to "<Your name> [automatic build]", or whatever you want.
  5. Click "Add".
  6. Repeat for GIT_EMAIL, also set to whatever you want.

Configure your project

  1. Copy the gh-publisher-scripts directory and all its contents from this repository into $PROJECT_DIR.
  2. Copy gh-publisher-scripts/example.travis.yml, and place it in $PROJECT_DIR/.travis.yml. Note that the name of this file is critical: it needs to be at the top level of your project, and it needs to be named .travis.yml -- with a period at the front and no period at the end.
  3. If necessary, edit gh-publisher-scripts/build.sh and gh-publisher-scripts/copy.sh. By default, these are configured to build the project by calling make at the top level, and then to copy *.pdf, *.html, *.css, *.js, *.png, *.jpeg, *.jpg, *.gif for publication. If you want to do something else, then you need to edit those files appropriately.
  4. Commit the entire contents of gh-publisher-scripts and your new .travis.yml to your repository, and push to GitHub.
  5. After a few minutes you should see your build begin, by looking at your status page on https://travis-ci.org.

Configure the front matter

You can optionally set the title and authors for the front section on the generated website. If you don't do this, default values will be inserted, derived from the project details. It will look a lot better if you set these values though.

  1. Edit gh-publisher-scripts/front-matter.yml to taste.
  2. Commit the changes and push to GitHub.

Check that it's all worked

  1. Visit https://$GITHUB_USERNAME.github.io/$REPO_NAME/. Hopefully you have a page here now! This can take up to ten minutes to appear the first time (future builds are instant).

Configuring other kinds of builds

The packages used for building are installed by .travis.yml. You can edit the list at the end if you need other packages as part of your build.

You can also edit gh-publisher-scripts/build.sh and gh-publisher-scripts/copy.sh to change what is built and what is copied before it is published.

Acknowledgments

gh-publisher was inspired by Phil Marshall, as part of Science Hack Day San Francisco 2014. https://github.com/drphilmarshall. http://sciencehackday.org.

The publishing template is derived from GitHub's automatic page generator, using the Minimal theme. https://github.com/orderedlist/minimal.

License

index.html, scale.fix.js, pygment_trac.css, styles.css: these are modified versions of https://github.com/orderedlist/minimal, which is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License. http://creativecommons.org/licenses/by-sa/3.0/.

The remaining files in this repository are by Ewan Mellor, and are dedicated to the public domain. To the extent possible under law, Ewan Mellor has waived all copyright and related or neighboring rights to this work. http://creativecommons.org/publicdomain/zero/1.0/.



gh-publisher

这是一个小的软件包,可以帮助您配置一个 自动构建和发布流程,使用Travis CI和GitHub页面。

gh出版社最初是为学术和科学论文而设计的 写在LaTeX。 LaTeX的每次更改都会触发自动化构建 重新生成PDF,然后发布。您可以轻松地扩展gh​​发布者 执行不同的构建过程,如下所述。

发布模板也被配置为接收您工作的反馈 通过GitHub问题。

这完全依赖于GitHub和Travis CI。

此处的示例点击github上的项目查看文件到位。

安装

我假设你有一个你自己的git仓库,包含任何东西 项目是你想要建立的。如果你还没有这样做, 您需要在GitHub上托管该存储库,并且需要本地克隆 在你的机器上如果你不知道该怎么做,请参阅 https://help.github.com

以下说明使用以下参考。替代正确 当您看到以下其中一个值时:

  1. $PROJECT_DIR: the directory containing your local clone of your project.
  2. $GITHUB_USERNAME: your GitHub username.
  3. $REPO_NAME: the name of your project's git repository.

在GitHub上启用问题跟踪

  1. Visit your repository settings at https://github.com/$GITHUB_USERNAME/$REPO_NAME/settings.
  2. In the Features section, ensure that Issues is checked.

< evenoddd =M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1 -1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2 -2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z> 启用Travis CI

上的自动构建
  1. Sign in to Travis CI using your GitHub credentials at https://travis-ci.org.
  2. Visit your Travis CI profile page at https://travis-ci.org/profile/$GITHUB_USERNAME.
  3. Click Sync now to refresh the list of repositories.
  4. Enable builds on your repository by flicking the appropriate switch.

允许Travis CI代表您发布到GitHub页面

您需要生成一个GitHub访问令牌。你会给这个 Travis CI,将授予其代表您的发布权。

  1. Visit your GitHub application settings at https://github.com/settings/applications.
  2. Under Personal access tokens, click "Generate new token". GitHub will ask for your password if you haven't entered it recently.
  3. Set the Token description to "Travis CI" (or whatever you want).
  4. Check "public_repo" as the scope, and uncheck all the other scopes. This limits Travis CI so that it is only able to publish to your public GitHub repositories, and can't modify anything else.
  5. Click Generate token.
  6. You will see a new token – a long string of numbers and letters. Leave this window open for now – this is the only time that you will see this token.
  7. In a new window, visit https://travis-ci.org/$GITHUB_USERNAME/$REPO_NAME/settings/env_vars.
  8. Click "Add a new variable".
  9. Set the Name to GH_TOKEN.
  10. Set the Value to that long string of numbers and letters in the other window.
  11. Leave "Display value in build logs" turned off.
  12. Click "Add".
  13. You can close the window with your GitHub access token now, you're done.

配置git提交使用的名称和电子邮件地址

您可以选择设置git提交中使用的名称和电子邮件地址 页面发布时。如果你不这样做,他们会出来 由gh-publisher&lt; not.a.real.person@example.com>自动构建。

  1. Visit https://travis-ci.org/$GITHUB_USERNAME/$REPO_NAME/settings/env_vars.
  2. Click "Add a new variable".
  3. Set the Name to GIT_NAME.
  4. Set the Value to "<Your name> [automatic build]", or whatever you want.
  5. Click "Add".
  6. Repeat for GIT_EMAIL, also set to whatever you want.

配置项目

  1. Copy the gh-publisher-scripts directory and all its contents from this repository into $PROJECT_DIR.
  2. Copy gh-publisher-scripts/example.travis.yml, and place it in $PROJECT_DIR/.travis.yml. Note that the name of this file is critical: it needs to be at the top level of your project, and it needs to be named .travis.yml – with a period at the front and no period at the end.
  3. If necessary, edit gh-publisher-scripts/build.sh and gh-publisher-scripts/copy.sh. By default, these are configured to build the project by calling make at the top level, and then to copy .pdf, .html, .css, .js, .png, .jpeg, .jpg, .gif for publication. If you want to do something else, then you need to edit those files appropriately.
  4. Commit the entire contents of gh-publisher-scripts and your new .travis.yml to your repository, and push to GitHub.
  5. After a few minutes you should see your build begin, by looking at your status page on https://travis-ci.org.

配置前端事物

您可以选择在前面部分设置标题和作者 生成网站。如果不这样做,将插入默认值, 源自项目细节。如果你设置的话会看起来好多了 这些值虽然。

  1. Edit gh-publisher-scripts/front-matter.yml to taste.
  2. Commit the changes and push to GitHub.

检查它是否正常工作

  1. Visit https://$GITHUB_USERNAME.github.io/$REPO_NAME/. Hopefully you have a page here now! This can take up to ten minutes to appear the first time (future builds are instant).

配置其他种类的构建

用于构建的包由 .travis.yml 安装。你可以编辑 如果您需要其他软件包作为构建的一部分,则在最后的列表。

您还可以编辑 gh-publisher-scripts / build.sh gh-publisher-scripts / copy.sh 来更改内置的内容和复制的内容 在发布之前。

致谢

作为科学黑客日的一部分,发布者受到菲尔·马歇尔的启发 旧金山2014年。 https://github.com/drphilmarshall http://sciencehackday.org

发布模板派生自GitHub的自动页面生成器, 使用最小主题。 https://github.com/orderedlist/minimal

许可证

index.html,scale.fix.js,pygment_trac.css,styles.css:这些被修改 https://github.com/orderedlist/minimal 的版本,其授权为 知识共享署名 - ShareAlike 3.0 Unported许可。 http://creativecommons.org/licenses/by-sa/3.0/

该存储库中的剩余文件由Ewan Mellor提供,并且是专用的 到公共领域。 在可能的范围内,Ewan Mellor已经放弃了所有的版权 相关或相邻的权利。 http://creativecommons.org/publicdomain/zero/1.0/




相关问题推荐