Skip to content

Add gh-pages docs publish task #1800

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add gh-pages docs publish task #1800

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 69 additions & 5 deletions Rakefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,7 @@ Bundler::GemHelper.install_tasks

require 'yard'

namespace :yard do
YARD::Rake::YardocTask.new(:doc) do |t|
t.stats_options = ['--list-undoc']
end

namespace :doc do
desc 'start a gem server'
task :server do
sh 'bundle exec yard server --gems'
Expand All @@ -28,6 +24,74 @@ namespace :yard do
sh "bundle exec yard graph --protected --full --dependencies > #{output_file}"
puts 'open doc/erd.dot if you have graphviz installed'
end

# #files => Array<String>
# The Ruby source files (and any extra documentation files separated by '-') to process.
DOC_FILES = ['lib/**/*.rb', '-', 'README.md']
DOC_FILES.concat Rake::FileList['docs/**/*.md'].to_a
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

still building these to wrong relative url, e.g. https://rails-api.github.io/active_model_serializers/file.configuration_options.html instead of in docs

DOC_FILES.freeze
DOC_REF = `git log --pretty=format:'%h' -1 | less -F -X`.chomp
DOC_VERSION = ActiveModel::Serializer::VERSION
DOC_REMOTE = "[email protected]:rails-api/active_model_serializers.git"
DOC_REMOTE_NAME = 'origin'
DOC_ROOT = File.expand_path('..', __FILE__)
DOC_PATH = File.join('..', 'ams.doc')
DOC_DIR = File.join(DOC_ROOT, DOC_PATH)

YARD::Rake::YardocTask.new(:doc) do |t|
t.stats_options = ['--list-undoc']
t.files = DOC_FILES
end

YARD::Rake::YardocTask.new(:pages) do |t|
t.files = DOC_FILES
t.options = ['-o', DOC_PATH]
end

namespace :pages do
task :clean do
Dir.chdir(DOC_DIR) do
next unless File.directory?('.git')
sh 'git rm -rf . || echo $?' if system("git diff HEAD^..HEAD &>/dev/null | cat")
end
end

desc 'Check out gh-pages.'
task :checkout do
unless Dir.exist?(DOC_DIR)
Dir.mkdir(DOC_DIR)
Dir.chdir(DOC_DIR) do
sh 'git init'
sh "git remote add #{DOC_REMOTE_NAME} #{DOC_REMOTE}"
sh "git fetch #{DOC_REMOTE_NAME}"
if system('git branch -r gh-pages')
sh "cat .git/HEAD | grep -q 'gh-pages' || git checkout gh-pages || echo $?"
sh "git reset --hard #{DOC_REMOTE_NAME}/#{gh-pages}"
else
sh 'git checkout --orphan gh-pages'
sh 'git rm -rf . || echo $?'
sh 'echo "Page" > index.html'
sh 'git add index.html'
sh 'git commit -a -m "First pages commit"'
sh "git push #{DOC_REMOTE_NAME} gh-pages --force-with-lease"
end
end
end
end

desc 'Generate and publish YARD docs to GitHub pages.'
task publish: ['doc:pages:checkout', 'doc:pages:clean', 'doc:pages'] do
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

compare to https://github.com/X1011/git-directory-deploy/blob/e37ac94cda4bfc5773c0f01d89d8c875a21ab4f9/deploy.sh#L5-L88 as described by https://gohugo.io/tutorials/github-pages-blog/

setup gh-pages

# Create a new orphand branch (no commit history) named gh-pages
git checkout --orphan gh-pages

# Unstage all files
git rm --cached $(git ls-files)

# Grab one file from the master branch so we can make a commit
git checkout master README.md

# Add and commit that file
git add .
git commit -m "INIT: initial commit on gh-pages branch"

# Push to remote gh-pages branch
git push origin gh-pages

# Return to master branch
git checkout master

# Remove the public folder to make room for the gh-pages subtree
rm -rf public

# Add the gh-pages branch of the repository. It will look like a folder named public
git subtree add --prefix=public [email protected]:spencerlyon2/hugo_gh_blog.git gh-pages --squash

# Pull down the file we just committed. This helps avoid merge conflicts
git subtree pull --prefix=public [email protected]:spencerlyon2/hugo_gh_blog.git gh-pages

# Run hugo. Generated site will be placed in public directory (or omit -t ThemeName if you're not using a theme)
hugo -t ThemeName


# Add everything
git add -A

# Commit and push to master
git commit -m "Updating site" && git push origin master

# Push the public subtree to the gh-pages branch
git subtree push --prefix=public [email protected]:spencerlyon2/hugo_gh_blog.git gh-pages

then

# deploy.sh
#!/bin/bash

echo -e "\033[0;32mDeploying updates to GitHub...\033[0m"

# Build the project.
hugo

# Add changes to git.
git add -A

# Commit changes.
msg="rebuilding site `date`"
if [ $# -eq 1 ]
  then msg="$1"
fi
git commit -m "$msg"

# Push source and build repos.
git push origin master
git subtree push --prefix=public [email protected]:spencerlyon2/hugo_gh_blog.git gh-pages

or

# Fetch the deployment script into the root of your source tree, make it executable.
wget https://github.com/X1011/git-directory-deploy/raw/master/deploy.sh && chmod +x deploy.sh

# For setting it up to build to a folder other than "dist", see the options in deploy.sh.
# Build the site to /dist.
hugo -d dist

# Run the deploy.sh script installed above.
./deploy.sh

or

#!/bin/bash

echo -e "\033[0;32mDeploying updates to GitHub...\033[0m"

# Build the project.
hugo # if using a theme, replace by `hugo -t <yourtheme>`

# Go To Public folder
cd public
# Add changes to git.
git add -A

# Commit changes.
msg="rebuilding site `date`"
if [ $# -eq 1 ]
  then msg="$1"
fi
git commit -m "$msg"

# Push source and build repos.
git push origin master

# Come Back
cd ..

Copy link
Member Author

@bf4 bf4 Dec 8, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also see https://github.com/dbfit/dbfit/blob/f6bfc5147b9a37443ce6106bf06aa6ff6855e133/bin/publish-to-gh-pages.sh

#!/bin/bash

git checkout gh-pages && git reset --hard origin/gh-pages && git checkout master && git reset --hard origin/master
parent_sha=$(git show-ref -s refs/heads/gh-pages)
doc_dir='docs'
doc_sha=$(git ls-tree -d HEAD $doc_dir | awk '{print $3}')
doc_commit_message=$(git log -n 1 --format="%s" $doc_dir)
new_commit=$(echo $doc_commit_message | git commit-tree $doc_sha -p $parent_sha)
git update-ref refs/heads/gh-pages $new_commit
git push origin gh-pages

Dir.chdir(DOC_DIR) do
sh "cat .git/HEAD | grep -q 'gh-pages' || git checkout gh-pages || echo $?"
sh 'git add .'
sh 'git add -u'
sh 'git diff --stat | cat'
sh 'git diff --stat --staged | cat'
sh 'git remote -v'
sh "git commit -m 'Generating docs for version #{DOC_VERSION} at ref #{DOC_REF}.' && git push #{DOC_REMOTE_NAME} gh-pages --force-with-lease || echo $!"
end
end
end
end

begin
Expand Down