Page History
Content
Table of Contents |
---|
Note |
---|
|
Create local release
As usually, nothing special:
Code Block |
---|
cd <some-directory>
source /reg/g/psdm/bin/conda_setup
condarel --newrel --name con-doc # name is arbitrary
cd con-doc
source /reg/g/psdm/bin/conda_setup |
Add package/repository from github
Being on pslogin (now it also works on psana nodes):
Code Block |
---|
git clone https://github.com/lcls-psana/psalgosmypackage.git # or condarel --addpkg --name psalgosmypackage --tag HEAD |
Set up sphinx within main repository
Add Sphinx configuration files in the directory web
. The name web
is arbitrary but for the purpose of further automation it would be nice to respect it as static.
Code Block |
---|
mkdir psalgosmypackage/doc/web cd psalgosmypackage/doc/web sphinx-quickstart |
...
Code Block |
---|
> Project name: psalgosmypackage-doc > Author name(s): Your Name and Titles Here > Project version []: 1.1 > Project release [1.1]: 1 > autodoc: automatically insert docstrings from modules (y/n) [n]: y > intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y > viewcode: include links to the source code of documented Python objects (y/n) [n]: y > githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: y |
In principle now documentation can be generated. But we do not want to mix it with code and will add it to the separate branch with static name gh-pages
doing tricks as follows.
Set up separate directory and repository for documentation
Code Block |
---|
mkdir ../../../psalgosmypackage-doc # arbitrary, but the same path should be in the Makefile... cd ../../../psalgosmypackage-doc git clone https://github.com/lcls-psana/psalgosmypackage.git html cd html |
Create new branch, set link, clean-up
Code Block |
---|
git branch gh-pages # this is a static name recognized by github... git symbolic-ref HEAD refs/heads/gh-pages rm .git/index git clean -fdx # A-A-A-A !!! this command removesdeletes everything ... from the branch gh-pages, not master git branch # just check that you are in * gh-pages |
...
Need to change BUILDDIR in order to not spoil master branch
Code Block |
---|
cd ../../psalgosmypackage/doc/web/ emacs Makefile -------------- # BUILDDIR = build BUILDDIR = ../../../psalgosmypackage-doc |
index.rst
Add something like
...
assuming that we are in .../con-doc/psalgosmypackage/doc/web
Code Block |
---|
cd .../psalgos sconsmypackage scons # I am not sure, but it probably needs to be done for cross-references... cd doc/web make html |
Commit changes to gh-pages
Code Block |
---|
cd ../../../psalgosmypackage-doc/html git branch # make sure that it is * gh-pages git status git add -A git commit -m "add/update doc" git push origin gh-pages |
Change GitHub Pages settings
This step needs to done if mypackage already has associated Wiki pages. By default the link to documentation https://lcls-psana.github.io/
psalgosmypackage/ points to master repo documentation. This needs to be changed to gh-pages in Setting for psalgos mypackage repo.
On https://github.com/lcls-psana/
psalgosmypackage.git click Settings and , scroll down to section GitHub Pages, and set correct Source pointing to gh-pages branch, then save settings.
See documentation
https://lcls-psana.github.io/mypackage/
For example:
- https://lcls-psana.github.io/psalgos/
- https://lcls-psana.github.io/PSCalib
- https://lcls-psana.github.io/Detector/
References
- http://lucasbardella.com/blog/2010/02/hosting-your-sphinx-docs-in-github
- https://daler.github.io/sphinxdoc-test/includeme.html
- https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/
...