Skip to content

my-githubpages-procedure-for-projects.md

Latest commit

 

History

History
executable file
·
118 lines (85 loc) · 4.3 KB

my-githubpages-procedure-for-projects.md

File metadata and controls

executable file
·
118 lines (85 loc) · 4.3 KB

Create GitHub web pages for your Arduino library project

Keep GitHub Pages for projects in the same repository as the main project, e.g., LedTask, but in a separate gh-pages branch. Use the master branch for core content, i.e., your project library source code.

You can do this by "orphan" -ing off a gh-pages branch of the repository. This new orphan branch has no history and commits, which allows you to make the webpages history independent of your original library source code.

I will create a GitHub Page for my project LedTask. In addition, I intend to publish class documentation generated by Doxygen. I only push static web pages and do not use GitHub Jekyll webpages machinery to build the site.

Create the new branch 'gh-pages'

The alias git sw2 is really git checkout, and git sta is git status. It's just a little shorter and easier to remember.

cd LedTask
git sw2 --orphan gh-pages        
git sta

Remove the git files that belong to the library in the 'master' branch

Remove the files in the gh-pages branch that only belongs to Gits master branch and the code development. These files are the ones that the git sta shows—for example, src-folder, examples-folder, LICENSE, README.md, etc., for an Arduino library project.

The branch likely contains other files and directories, usually excluded in the .gitignore file. Do not delete non-git-indexed files (Makefile, LedTask.doxyfile, ...) and directories (test, build,...). The git sta output tells you which files should be removed (but keep the .gitignore file) in the gh-pages branch.

rm -fr src
rm -fr examples
rm -fr images
rm LICENSE
rm README.md
rm library.properties
rm keywords.txt
...

It is a good idea to keep the .gitignore from the master branch.

Prepare for the GitHub pages content

It's possible to keep the GitHub page content in the root-folder or a subdirectory named /docs. However, Doxygen generates lots of files in the same directory. Therefore I chose the latter alternative with /docs. Since we will push ready-made static web pages, we add the .nojekyll file in the root as required.

mkdir docs
touch .nojekyll

../LedTask (gh-pages)$ ls -la
    drwxr-xr-x 4 bekr bekr 4096 Sep  4 21:44 .
    drwxr-xr-x 8 bekr bekr 4096 Sep  4 19:38 ..
    drwxr-xr-x 2 bekr bekr 4096 Sep  4 21:37 docs
    drwxr-xr-x 8 bekr bekr 4096 Sep  4 21:39 .git
    -rw-r--r-- 1 bekr bekr  214 Sep  4 11:31 .gitignore
    -rw-r--r-- 1 bekr bekr    0 Sep  4 21:38 .nojekyll
    ...
    ...

Commit to Git.

git add .
git commit -m 'initial Github pages commit'

Add static content for GitHub pages to an existing site

Copy generated Doxygen content, i.e., all files recursively from the /html folder to /docs in the gh-pages branch. The site https://berrak.github.io/LedTask/ already exist.

  • Push the documentation. The --set-upstream means that the local repo tracks change upstream.
git add .
git com -m 'add GitHub pages content'
git push --set-upstream origin gh-pages

In this case, the repository (master branch) already existed.

Push content to a new repository

If this is a new repository, use git remote first.

git remote add origin https://github.com/berrak/LedTask.git
git vre
git push -u origin gh-pages

Tell GitHub to build your newly uploaded content

The remaining action is to tell GitHub to fetch the content from the docs folder.

Follow GitHub instruction to name the branch for your GitHub pages files.

Finally, view the Doxygen generated class documentation for the project LedTask.

Update GitHub pages content

Add and push additional content to the GitHub repository on the gh-pages branch.

git add .
git com -m 'some comment'
git push

Later, work with the 'master' and the 'gh-pages' branches

Switch to the master branch and push updates to the Arduino library files as usual.

git sw2 master
...
git push

If GitHub pages need to be updated or added, switch to gh-pages branch and push any changes.

git sw2 gh-pages
...
git push