Documentation

  • last updated 6/28 Andrew Kan

Latest Commit and Branch

To obtain latest commit and branch, run

git show –oneline -s

and

git branch

on your current directory

branch: new_dynamic_xc

commit: 6272c14 Merged in yaohanqing/sally_calsim/new_dynamic_xc (pull request #277)

Changes to files:

in utility_modules/get_parameters, I had to change from dotmap to .dotMap

in utility_modules/dotMap, I had to change DotDict to DotMap (because of python 3)

in main.py, I had to change DotDict to DotMap, also changed urllib2 to urllib.error

in calsim.py, changed all print to print()

in output.py, changed import import_zip.py to import utility_modules.import_zip.py

in selectfirm.py, added some documentation

after running sphinx-apidoc -o ./source . to generate the .rst files (see below), I deleted modules.rst as it was unnecessary; we already have utility_modules and policy_modules.

I also got rid of all the “modules” from headings/section titles to make them easier to read

Adding individual files:

  1. add folder with .py files to main folder

  2. make a rst file with this format http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#paragraph-level-markup or https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst for help

_images/rst-format.png

or you can run sphinx-apidoc -o ./source .

  1. add the rst file (inside source) to index.rst

_images/rst-format-0.png

  1. run make clean

  2. run make html

Adding every file:

  1. copy the entire calsim folder

2. rename the folder to “files” 2. sphinx-apidoc -o ./source . 3-6. same as steps 3-6 above

Adding Documentation to Files:

  1. Simply add the comments to the functions in docstring format

  2. Follow this example for docstring: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html/

  3. example

“”“
parameters:
f_name: name of file
f_type: format of file
output:
pandas dataframe workbook
“”“

  1. You can use docstrings to specify parameters, returns, notes, attributes, etc.

  2. Only these types of comments will be documented. Additionally, the docstring must be placed right after the function declaration. Docstrings inside functions will not be shown

Navigation

  • You can use the links on the left or center of the page to navigate to your desired file/function

  • Clicking the bolded calsim on the top left returns you to the home page

  • Once you click on a link to a file, it will show all of its functions (regardless if they have docstrings or not) with their docstring comments - It will also display each function’s parameters. - Clicking on the ‘source’ link on the right of a function will show you its source code

  • Index is an index of every single function

  • Module Index is an index of every single file

File Navigation

  • the configuration file (conf.py) and the rst files are located in the source folder

  • the current CalSim repository is in the calsim folder

  • the current bitbucket wiki markdown files are in the wiki folder

  • the actual html pages for this website are in the build/html folder

Other