Create local release
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
git clone https://github.com/lcls-psana/psalgos.git # or condarel --addpkg --name psalgos --tag HEAD
Set up sphinx within main repository
mkdir psalgos/doc/web cd psalgos/doc/web sphinx-quickstart
Then in dialog with sphinx-quickstart type-in non-default answers for options as follows.
> Project name: psalgos-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, doing tricks as follows.
Set up separate directory and repository for documentation
mkdir ../../../psalgos-doc # arbitrary, but the same path should be in the Makefile... cd ../../../psalgos-doc git clone https://github.com/lcls-psana/psalgos.git html cd html
Create new branch, set link, clean-up
git branch gh-pages git symbolic-ref HEAD refs/heads/gh-pages rm .git/index git clean -fdx # A-A-A-A !!! this command removes everything ... from the branch gh-pages, not master git branch # just check that you are in * gh-pages
Makefile changes
Need to change BUILDDIR in order to not spoil master branch
cd ../../psalgos/doc/web/ emacs Makefile -------------- # BUILDDIR = build BUILDDIR = ../../../psalgos-doc
index.rst changes
Add something like
:maxdepth: 3 .. automodule:: <your module name> :members: :show-inheritance: :special-members: :private-members: .. autosummary:: :toctree: _autosummary
conf.py changes
At least need to set path to the source files which docstrings are going to be used:
import os
import sys
sys.path.insert(0, os.path.abspath('../../src')) # ABSOLUTE PATH!!!
# for my personal preferences:
'sphinx.ext.autosummary'
autosummary_generate = True
# html_theme = 'alabaster'
html_theme = 'agogo'
# 'about.html',
# 'donate.html',
#add:
def setup(app):
app.add_stylesheet('my_theme.css')
Add _static/my_theme.css containing
.wy-nav-content {
max-width: 900px !important;
}
Commit changes
git add -A dir status git commit -m "add sphinx doc" git push origin master
Generate documentation
assuming that we are in .../con-doc/psalgos/doc/web
cd .../psalgos scons cd doc/web make html
Commit changes of documentation branch
cd ../../../psalgos-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
See documentation
https://lcls-psana.github.io/psalgos/
References
Create local release
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
git clone https://github.com/lcls-psana/psalgos.git # or condarel --addpkg --name psalgos --tag HEAD
Set up sphinx within main repository
mkdir psalgos/doc/web cd psalgos/doc/web sphinx-quickstart
Then in dialog with sphinx-quickstart type-in non-default answers for options as follows.
> Project name: psalgos-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, doing tricks as follows.
Set up separate directory and repository for documentation
mkdir ../../../psalgos-doc # arbitrary, but the same path should be in the Makefile... cd ../../../psalgos-doc git clone https://github.com/lcls-psana/psalgos.git html cd html
Create new branch, set link, clean-up
git branch gh-pages git symbolic-ref HEAD refs/heads/gh-pages rm .git/index git clean -fdx # A-A-A-A !!! this command removes everything ... from the branch gh-pages, not master git branch # just check that you are in * gh-pages
Makefile changes
Need to change BUILDDIR in order to not spoil master branch
cd ../../psalgos/doc/web/ emacs Makefile -------------- # BUILDDIR = build BUILDDIR = ../../../psalgos-doc
index.rst changes
Add something like
:maxdepth: 3 .. automodule:: <your module name> :members: :show-inheritance: :special-members: :private-members: .. autosummary:: :toctree: _autosummary
conf.py changes
At least need to set path to the source files which docstrings are going to be used:
import os import sys sys.path.insert(0, os.path.abspath('../../src')) # ABSOLUTE PATH!!! # for my personal preferences: 'sphinx.ext.autosummary' autosummary_generate = True # html_theme = 'alabaster' html_theme = 'agogo' # 'about.html', # 'donate.html', #add: def setup(app): app.add_stylesheet('my_theme.css')Add _static/my_theme.css containing
.wy-nav-content { max-width: 900px !important; }Commit changes
git add -A dir status git commit -m "add sphinx doc" git push origin master
Generate documentation
assuming that we are in .../con-doc/psalgos/doc/web
cd .../psalgos scons cd doc/web make html
Commit changes of documentation branch
cd ../../../psalgos-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
See documentation
https://lcls-psana.github.io/psalgos/
References
- http://lucasbardella.com/blog/2010/02/hosting-your-sphinx-docs-in-github
- https://daler.github.io/sphinxdoc-test/includeme.html
Overview
Content Tools