Documentation

This is (partial) documentation for the McCoy group packages. The listing here is automatically generated by our Peeves unit-testing/documentation building package.

We have documentation for these packages:

Help Us Out!

Each page should support examples, but unfortunately most do not, simply because writing that kind of thing by hand is time consuming. If you see a page without examples, help us out! Even though these pages are automatically generated, you can add examples to them by putting a file in the appropriate examples slot and rebuilding the docs via the docs.py script we’ve provided. At some point that will become part of a CI process, but we’re unfortunately not there yet. If you want to just let us know that you added some examples so we can trigger a build, that can be done via the issues page. Similarly, if you see something that you think should be improved, you can either edit the docstrings in the source or let us know about the deficiency here.

Examples

To contribute an example for a page at

https://mccoygroup.github.io/References/Documentation/McUtils/GaussianInterface.html

you’ll either add the appropriate file by going to

https://github.com/McCoyGroup/References/new/gh-pages?filename=Documentation/examples/McUtils/GaussianInterface.md

or edit the existing one by going to

https://github.com/McCoyGroup/References/edit/gh-pages/Documentation/examples/McUtils/GaussianInterface.md
Documentation

For this, you’ll need to navigate to the appropriate package. The breadcrumbs on the documentation pages can be very helpful for this. Say you wanted to edit some docstring on the Molecule class. To do so you’d first note that in the breadcrumb we have

Documentation / Psience / Molecools

So you’d go to https://github.com/McCoyGroup/Psience/Molecools & then notice that there is a package called Molecule.py. Then, clicking on the package’s edit link ( McCoyGroup/Psience/edit/master/Molecools/Molecule.py ) you can navigate to where Molecule is defined and edit that. Alternately, if you know the line number in the source file, you can link directly to that line in the source and then people can use the GitHub UI.

After editing, you’ll need to rerun the site build via the GitHub Action we set up.

Templates

The documentation build makes use of a template system to generate its Markdown pages. In particular, it uses the files here to make this work, where the following hiearchy is used:

  • index.md is used for this main index page
  • module.md is used for modules
  • class.md is used for classes
  • function.md is used for stand-alone functions
  • method.md is used for object methods
  • object.md is used for objects with a __name__ parameter

You can also add custom templates for pages, if you feel they need more information than the auto-generator can provide. To do so, we’ll add to the file path in the templates directory of the documentation.

For the McUtils.GaussianInterface example from before, to edit the template we would have

https://github.com/McCoyGroup/References/edit/gh-pages/Documentation/templates/McUtils/GaussianInterface.md

and or to make the file we’d use

https://github.com/McCoyGroup/References/new/gh-pages?filename=Documentation/templates/McUtils/GaussianInterface.md

once Peeves has a chance to rebuild the site, the new template will be used.

It’s generally good to build off of the old templates, though, so that we don’t lose information.