Versions Compared

Old Version 1

changes.mady.by.user Mikhail Dubrovin

Saved on

compared with

New Version 2

changes.mady.by.user Mikhail Dubrovin

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Content

Table of Contents

Note

This example uses package name psalgos, which should be replaced by the real package name.

Create local release

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
 Code Block
git clone https://github.com/lcls-psana/psalgos.git
# or
condarel --addpkg --name psalgos --tag HEAD
 
Set up sphinx within main repository
...
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
...
 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 removes everything ... from the branch gh-pages, not master
git branch # just check that you are in * gh-pages
...
Change configuration files
Makefile
...
Need to change BUILDDIR in order to not spoil master branch
 Code Block
cd ../../psalgos/doc/web/
emacs Makefile
--------------
# BUILDDIR      = build
BUILDDIR      = ../../../psalgos-doc
 
index.rst
...
Add something like
 Code Block
:maxdepth: 3

.. automodule:: <your module name>
   :members:
   :show-inheritance:
   :special-members:
   :private-members:
.. autosummary::
   :toctree: _autosummary
 
conf.py
...
At least need to set path to the source files which docstrings are going to be used:
...
 Code Block
.wy-nav-content {
    max-width: 900px !important;
}
Commit changes to master
 Code Block
git add -A
dir status
git commit -m "add sphinx doc"
git push origin master
...
 Code Block
cd .../psalgos
scons

cd doc/web
make html
Commit changes 
...
to gh-pages
 Code Block
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
Change GitHub Pages settings
By default the link to documentation https://lcls-psana.github.io/psalgos/
References
Create local release
 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
 Code Block
git clone https://github.com/lcls-psana/psalgos.git
# or
condarel --addpkg --name psalgos --tag HEAD
 
Set up sphinx within main repository
 Code Block
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.
 Code Block
> 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
...
 points to master repo documentation. This needs to be changed to gh-pages in Setting for psalgos repo.
On https://github.com/lcls-psana/psalgos.git
...
 click Settings and scroll down to section GitHub Pages and set correct Source pointing to gh-pages branch.
Create new branch, set link, clean-up
 Code Block
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
 Code Block
cd ../../psalgos/doc/web/
emacs Makefile
--------------
# BUILDDIR      = build
BUILDDIR      = ../../../psalgos-doc
 
index.rst changes
Add something like
 Code Block
: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:
 Code Block
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
 Code Block
.wy-nav-content {
    max-width: 900px !important;
}
Commit changes
 Code Block
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
 Code Block
cd .../psalgos
scons

cd doc/web
make html
Commit changes of documentation branch
 Code Block
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