joshua/dash-docs
1
0
Fork 0
mirror of https://github.com/seigler/dash-docs synced 2025-07-26 01:06:13 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Travis-CI deploy to GH Pages (#21)

Browse source 
build - Travis-CI deploy to GH Pages
 - Scripts/config necessary to allow automatic build/deploy from Travis-CI
This commit is contained in:
thephez 2018-02-05 16:21:58 -05:00 • committed by GitHub
parent deaa367a1d
commit a3e446bbb0
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 146 additions and 309 deletions
Download patch file Download diff file Expand all files Collapse all files

46
.travis.yml
View file

@ -3,13 +3,59 @@ rvm:
- "2.5.0"
sudo: false
cache: bundler
cache:
directories:
- $TRAVIS_BUILD_DIR/doxygen-install
env:
# http://docs.travis-ci.com/user/environment-variables/#Global-Variables
global:
- BITCOINORG_BUILD_TYPE=deployment
- DOXYFILE: Doxyfile-dashdocs
# Install dependencies
addons:
apt:
packages:
- flex
- bison
- build-essential
- graphviz
before_install:
- gem update --system
- gem install bundler
- cd $TRAVIS_BUILD_DIR
- chmod +x scripts/build-install-doxygen.sh
- ./scripts/build-install-doxygen.sh
script: make travis
# Generate and deploy documentation
after_success:
- cd $TRAVIS_BUILD_DIR
- chmod +x scripts/generateDocumentationAndDeploy.sh
- ./scripts/generateDocumentationAndDeploy.sh
deploy:
# Set these environment variables in travis-ci.org settings for the repo:
#
# GITHUB_TOKEN: token that allows Travis to deploy to GitHub (mark secure)
# DEPLOY_REPO_NAME: GitHub repo to deploy to (i.e dash-docs/dash-docs.github.io)
# DEPLOY_TARGET_BRANCH: Branch to deploy to (must be master for page to work correctly)
#
# *** NOTE: the target branch is overwritten on deployment. Use caution to
# avoid inadvertently overwriting something
#
# DEPLOY_SOURCE_BRANCH: Branch to deploy from
provider: pages
skip-cleanup: true
github-token: $GITHUB_TOKEN # Set in travis-ci.org dashboard, marked secure
keep-history: false
on:
branch: $DEPLOY_SOURCE_BRANCH
verbose: false
local-dir: _site/
repo: $DEPLOY_REPO_NAME
target_branch: $DEPLOY_TARGET_BRANCH

308
docs/adding-events-release-notes-and-alerts.md
View file

@ -1,308 +0,0 @@
## Adding Events, Release Notes and Alerts
### Events
If you're not comfortable with GitHub pull requests, please open a [new issue](https://github.com/bitcoin-dot-org/bitcoin.org/issues/new?title=New%20event&body=%20%20%20%20-%20date%3A%20YYYY-MM-DD%0A%20%20%20%20%20%20title%3A%20%22%22%0A%20%20%20%20%20%20venue%3A%20%22%22%0A%20%20%20%20%20%20address%3A%20%22%22%0A%20%20%20%20%20%20city%3A%20%22%22%0A%20%20%20%20%20%20country%3A%20%22%22%0A%20%20%20%20%20%20link%3A%20%22%22).
To create an event pull request, place the event in `_events.yml` and adhere to
this format:
```
- date: 2014-02-21
title: "2014 Texas Bitcoin Conference"
venue: "Circuit of the Americas™ - Technology and Conference Center"
address: "9201 Circuit of the Americas Blvd"
city: "Austin, TX"
country: "United States"
link: "http://texasbitcoinconference.com/"
```
### Release Notes
To create a new Bitcoin Core release, create a new file in the
`_releases/` directory. Any file name ending in `.md` is fine, but we
recommend naming it after the release, such as `0.10.0.md`
Then copy in the following YAML header (the part between the three dashes, ---):
```
---
# This file is licensed under the MIT License (MIT) available on
# http://opensource.org/licenses/MIT.
## Required value below populates the %v variable (note: % needs to be escaped
in YAML if it starts a value)
required_version: 0.10.0
## Optional release date. May be filled in hours/days after a release
optional_date: 2015-02-16
## Optional title. If not set, default is: Bitcoin Core version %v released
optional_title: Bitcoin Core version %v released
## Optional magnet link. To get it, open the torrent in a good BitTorrent
client
## and View Details, or install the transmission-cli Debian/Ubuntu package
## and run: transmission-show -m <torrent file>
#
## Link should be enclosed in quotes and start with: "magnet:?
optional_magnetlink:
## The --- below ends the YAML header. After that, paste the release notes.
## Warning: this site's Markdown parser commonly requires you make two
## changes to the release notes from the Bitcoin Core source tree:
##
## 1. Make sure both ordered and unordered lists are preceded by an empty
## (whitespace only) line, like the empty line before this list item.
##
## 2. Place URLs inside angle brackets, like <http://bitcoin.org/bin>
---
```
Then start at the top of the YAML header and read the comments, filling
in and replacing information as necessary, and then reformatting the
release notes (if necessary) as described by the last lines of the YAML
header.
Download links will automatically be set to the defaults using the current
release version number, but if you need to change any download URL, edit
the file `_templates/download.html`
You can then create a pull request to the
master branch and Travis CI will automatically build it and make sure
the links you provided return a "200 OK" HTTP header. (The actual files
will not be downloaded to save bandwidth.) Alternatively, you can build
the site locally with `make all` to run the same quality assurance tests.
The file can be edited later to add any optional information (such as a
release date) that you didn't have when you created the file.
#### Preparing a release in advance
It's nice to prepare a release pull request in advance so that the
Bitcoin Core developers can just click "Merge Pull Request" when the new
version is released. Here's the recommended recipe, where `<VERSION>`
is the particular version:
1. Create a new branch named `bitcoin-core-<VERSION>`. You can either
do this locally or in GitHub's web GUI.
2. Follow the instructions in the [Release
Notes](https://github.com/bitcoin-dot-org/bitcoin.org/blob/master/docs/adding-events-release-notes-and-alerts.md#release-notes)
section to create a new release. You should leave the `optional_date` blank
unless you happen to know the date of the planned release.
3. Push the branch to the https://github.com/bitcoin-dot-org/bitcoin.org
repository so any contributor can edit it. **Don't** open a pull
request yet.
4. Travis CI will build the site from the branch and then run the tests.
The tests will fail because they expect the release binaries to be
present and you're preparing this release request in advance of them
being uploaded.
5. Open the failed Travis CI log. At the end, it will say something like:
```
ERROR:
Error: Could not retrieve /bin/bitcoin-core-0.10.1/bitcoin-0.10.1-win64-setup.exe
Error: Could not retrieve /bin/bitcoin-core-0.10.1/bitcoin-0.10.1-win32-setup.exe
[...]
```
6. Copy the errors from above into a text file and remove everything
except for the URLs so that what's left are lines that look like:
```
/bin/bitcoin-core-0.10.1/bitcoin-0.10.1-win64-setup.exe
/bin/bitcoin-core-0.10.1/bitcoin-0.10.1-win32-setup.exe
[...]
```
7. Optional, but nice: sort the lines into alphabetical order.
8. Now open a pull request from the `bitcoin-core-<VERSION>` branch to
the `master` branch. We recommend that you use this title: "Releases:
Add Bitcoin Core <VERSION>".
We recommend that you use the following text with any changes you
think are appropriate. **Note:** read all the way to the end of this
enumerated point before submitting your pull request.
```
This updates the download links to point to <VERSION> and adds the <VERSION>
release notes to the site. I'll keep it updated throughout the RC cycle, but it
can be merged by anyone with commit access once <VERSION> final is released (see
TODO lists below).
CC: @laanwj
```
Essential TODO:
* [ ] Make sure the download links work. This is automatically checked as part
of the Travis CI build, so trigger a rebuild and, if it passes, this should be
safe to merge.
Optional TODO (may be done in commits after merge):
* [ ] Add the actual release date to the YAML header in `_releases/0.10.1.md`
* [ ] Add the magnet URI to the YAML header in `_releases/0.10.1.md` (brief
instructions for creating the link are provided as comments in that file)
Expected URLs for the Bitcoin Core binaries:
Underneath the line 'Expected URLs', paste the URLs you retrieved from Travis CI
earlier.
Note that @laanwj is Wladimir J. van der Laan, who is usually responsible for
uploading the Bitcoin Core binaries. If someone else is responsible for this
release, CC them instead. If you don't know who is responsible, ask in
#bitcoin-dev on Freenode.
9. After creating the pull request, use the Labels menu to assign it the
"Releases" label. This is important because it's what the Bitcoin
Core release manager will be looking for.
10. After each new Release Candidate (RC) is released, update the
release notes you created in the `_releases` directory. (But don't
worry about this too much; we can always upload updated release
notes after the release.)
### Alerts
1. [Who to contact](#who-to-contact)
2. [Basic alert](#basic-alert) (emergency fast instructions)
3. [Detailed alert](#detailed-alert)
4. [Clearing an alert](#clearing-an-alert)
#### Who to Contact
The following people can publish alerts on Bitcoin.org. Their email
addresses are on the linked GitHub profiles.
- Will Binns, [@wbnns](https://github.com/wbnns), wbnns on Freenode
- Wladimir van der Laan, [@laanwj](https://github.com/laanwj), wumpus on
Freenode
- Theymos, [@theymos](https://github.com/theymos), theymos on Freenode
#### Basic Alert
1. Open your editor on a file named `_alerts/YYYY-MM-DD-short-title.md`
(the alert will appear as
<https://bitcoin.org/en/alert/YYYY-MM-DD-short-title>).
2. Paste the following text into the top of the file:
```
---
## Title displayed on alert page
title: "11/12 March 2017 Chain Fork"
## Short URL for use in P2P network alerts: https://bitcoin.org/<shorturl>
shorturl: "chainfork"
## Active alerts will display the banner (below) on all bitcoin.org content pages
active: true
## Banner displayed if 'active: true'. Can use HTML formatting banner: "<b>Chain fork</b> - Please stop mining on bitcoin version 0.14.1. Click here for more information."
## Date of the alert in YYYY-MM-DD format
date: 2017-03-11
---
{% comment %}
First paragraph should indicate whose bitcoins are safe, to avoid starting a panic.
{% comment %}
Your bitcoins are safe if you received them in transactions confirmed before 2015-07-06 00:00 UTC.
{% comment %}
Second paragraph should summarize the problem, and subsequent
text should indicate what people should do immediately.
Consider: users (by wallet type), merchants, and miners.
{% comment %}
However, there has been a problem with a planned upgrade. For
bitcoins received later than the time above, confirmation scores are
significantly less reliable then they usually are for users of
certain software:
- Lightweight (SPV) wallet users should wait an additional 30
confirmations more than you would normally wait. Electrum users,
please see this note.
```
- Edit the file. It is written in [Markdown format](https://guides.github.com/features/mastering-markdown/).
- Commit it.
- **Note:** the commit must be signed by one of the people in the
[Who to Contact](#who-to-contact) section for site
auto-building to work.
- Push the commit to the master branch. Rebuilding the site occurs
automatically and takes 7 to 15 minutes.
- **Note:** do not push additional commits until the alert is
displayed on the live site. The site build aborts and starts over
when new commits are found.
- Give the `shorturl` URL (`bitcoin.org/<shorturl>`) to the P2P alert message
key holders to use in any alert messages they send.
- Proceed to the next section to improve the alert.
#### Detailed Alert
In addition to providing more information about how users should respond
to the situation, you can enhance the alert in several ways described
below.
The following fields may be defined in the the alert YAML header:
```yaml
---
## (Required; HTML text) Title displayed on alert page
title: "11/12 March 2017 Chain Fork"
## (Optional; display ASCII only) Short URL for use in P2P network alerts:
https://bitcoin.org/<shorturl>
shorturl: "chainfork"
## (Optional; default=false) Active alerts will display the banner (below) on
all bitcoin.org content pages
active: true
## (Optional; HTML text) Banner displayed if 'active: true'. Can use HTML
formatting
banner: "<b>Chain fork</b> - Please stop mining on bitcoin version 0.14.1. Click
here for more information."
## (Optional; default=alert) CSS class to set banner color
## alert = red | warning = orange | success = green | info = blue
bannerclass: alert
---
```
The time of the last update should be placed on the page somewhere. UTC
should be used for all dates, and RFC 2822 format ( date -uR ) is
recommended for long dates. For example, place the date in the footer of
the document:
```html
<div style="text-align:right">
<i>This notice last updated: Thu, 16 May 2017 01:37:00 UTC</i>
</div>
```
You may also want to create a page on the Wiki to allow anyone to
provide additional information. If you do so, link to it from the
alert.
#### Clearing An Alert
To stop advertising an alert on every Bitcoin.org page, change the YAML
header field `active` to *false*:
```yaml
## (Optional; default=false) Active alerts will display the banner (below) on
all bitcoin.org content pages
active: false
```
Alternatively, for a few days you can change the message and set the
CSS `bannerclass` to *success* to indicate the problem has been resolved.
```yaml
## (Optional; HTML text) Banner displayed if 'active: true'. Can use HTML
formatting
banner: "<b>Chain fork</b> - situation resolved"
## (Optional; default=alert) CSS class to set banner color
## alert = red | warning = orange | success = green | info = blue
bannerclass: success
```
[markdown format]: https://help.github.com/articles/markdown-basics/

2
doxygen/Doxyfile-dashdocs
View file

@ -728,7 +728,7 @@ CITE_BIB_FILES =
# messages are off.
# The default value is: NO.
QUIET = NO
QUIET = YES
# The WARNINGS tag can be used to turn on/off the warning messages that are
# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES

39
scripts/build-install-doxygen.sh Normal file
View file

@ -0,0 +1,39 @@
#!/bin/sh
set -ex
file="$TRAVIS_BUILD_DIR/doxygen-install/doxygen"
# Only build Doxygen if the binary isn't found
if [ -f "$file" ]
then
echo "Doxygen binary found. Skipping build."
else
echo "Doxygen binary not found. Building from source..."
# Build instructions from: https://www.stack.nl/~dimitri/doxygen/download.html
echo "Cloning doxygen repository..."
git clone https://github.com/doxygen/doxygen.git doxygen-src
cd doxygen-src
# Use v1.8.14 (2f4139de014bf03898320a45fe52c92872c1e0f4)
git checkout 2f4139de014bf03898320a45fe52c92872c1e0f4 .
echo "Create build folder..."
mkdir build
cd build
echo "Make..."
cmake -G "Unix Makefiles" ..
make
echo "Done building doxygen..."
./bin/doxygen -v
echo "Copy Doxygen binary to folder for caching..."
mkdir -p $TRAVIS_BUILD_DIR/doxygen-install
cp bin/doxygen $TRAVIS_BUILD_DIR/doxygen-install/
cd $TRAVIS_BUILD_DIR
fi

60
scripts/generateDocumentationAndDeploy.sh Normal file
View file

@ -0,0 +1,60 @@
#!/bin/sh
################################################################################
# Title : generateDocumentationAndDeploy.sh
# Date created : 2016/02/22
# Notes :
__AUTHOR__="Jeroen de Bruijn"
# Preconditions:
# - Packages doxygen doxygen-doc doxygen-latex doxygen-gui graphviz
# must be installed.
# - Doxygen configuration file must have the destination directory empty and
# source code directory with a $(TRAVIS_BUILD_DIR) prefix.
# - An gh-pages branch should already exist. See below for mor info on hoe to
# create a gh-pages branch.
#
# Required global variables:
# - TRAVIS_BUILD_NUMBER : The number of the current build.
# - TRAVIS_COMMIT : The commit that the current build is testing.
# - DOXYFILE : The Doxygen configuration file.
# - GH_REPO_NAME : The name of the repository.
# - GH_REPO_REF : The GitHub reference to the repository.
# - GH_REPO_TOKEN : Secure token to the github repository.
#
# For information on how to encrypt variables for Travis CI please go to
# https://docs.travis-ci.com/user/environment-variables/#Encrypted-Variables
# or https://gist.github.com/vidavidorra/7ed6166a46c537d3cbd2
# For information on how to create a clean gh-pages branch from the master
# branch, please go to https://gist.github.com/vidavidorra/846a2fc7dd51f4fe56a0
#
# This script will generate Doxygen documentation and push the documentation to
# the gh-pages branch of a repository specified by GH_REPO_REF.
# Before this script is used there should already be a gh-pages branch in the
# repository.
#
################################################################################
################################################################################
##### Setup this script and get the current gh-pages branch. #####
echo 'Setting up the script...'
# Exit with nonzero exit code if anything fails
set -e
# Clone Dash Core
git clone https://github.com/dashpay/dash.git
cd dash
# Copy Doxygen config / build files
cp $TRAVIS_BUILD_DIR/doxygen/* doc/
################################################################################
##### Generate the Doxygen code documentation and log the output. #####
echo 'Generating Doxygen code documentation...'
# Redirect both stderr and stdout to the log file AND the console.
$TRAVIS_BUILD_DIR/doxygen-install/doxygen doc/$DOXYFILE 2>&1 | tee doxygen.log
echo 'Done generating Doxygen code documentation...'
#cat doxygen.log
# Copy Doxygen files to dash-docs folder
echo 'Copy Doxygen files to _site...'
cp -R doc/doxygen $TRAVIS_BUILD_DIR/_site/en/