Contributing¶
Contributing to the repository is fairly easy, so please see below for instructions on how to actually make contributions to this project.
Setup¶
There are two forms of contributions: source code or documentation. Editing the documentation is as simple as cloning the repo and adding/editing content within the docs folder. All documentation is written in markdown and converted to html through myst_parser and sphinx. To edit the source code, as well as the documentation, you will want to install the package through a symlink.
Note
A conda or virtualenv will add isolation to your python environments and reduce conflicts amongst packages. It is highly recommended to use one!!
Cloning the Repo¶
Clone the repo as normal:
git clone https://github.com/AaronYoung5/hydra-config.git && cd hydra-config
Installing a Symbolic Linked Version for Testing¶
A symbolic link or symlink is a file that references another. The advantages of symlinks is that a folder or file can essentially be placed in two separate locations. In reference to this repository, we want to create a symlinked install because when we edit the code within the cloned repo, we want that change also to be reflected in the installed files.
# You need the dev requirements to build the documentation
pip install -e .[dev]
Deploy your Changes¶
GitHub actions are used to automatically build the site and GitHub pages are used to host the static site. To update deployed content, you have to push to the main branch. Once the changes are pushed, the site will rebuild. Please ensure there are no errors in your code/documentation before doing so, as you may get an email from github if something bad happens.
Further, to update the package available on PyPI, you must create a git tag. When a tag is created and pushed to GitHub, it will start an Action which will automatically push the new release to PyPI. See Versioning for information on how versioning works with hydra-config. The Github Action only runs when the tag is pushed to main through a merge request. To create a tag, you may do the following:
git tag <tag> # An example tag is '3.0.1'
git push origin main --tags
Versioning¶
Versioning is done automatically through tags by setuptools_scm. When a tag is pushed to the main branch, a new package is pushed to PyPI with the attached tag. Therefore, you must ensure the tag you push is after the previous tags seen on GitHub (otherwise nothing will push to PyPI).
Guidelines¶
A lot of work has gone into making this package functional and scalable. Please consider all of the following guidelines and follow them to ensure the repository will persist for a long time.
File Structure¶
The repository is structured as follows:
hydra-config/
├── hydra_config/ # Source code for the package
├── docs/ # Documentation for the package
├── examples/ # Example code for the package
├── tests/ # Tests for the package
├── LICENSE # License file
└── pyproject.toml # Package configuration file
Editing the Source Code¶
If you plan on editing the source code, please visit the hydra_config/ folder. The hydra_config/ folder is structured as follows:
hydra_config/
├── utils.py # Utility functions for the package
├── config.py # Configuration class for the package
├── resolvers.py # Resolvers for the package
└── __init__.py # Initialization file for the package
Commenting¶
Please follow Google’s guidelines for Python Styling. These comments are also used to automatically generate the documentation. For Visual Studio Code users, the Python Docstring Generator package may be helpful.
Note
Any docstrings parsed by autosimple, such as the functions in Usage, are parsed as markdown. Docstrings parsed by autoapi, such as in hydra_config.config.HydraContainerConfig, are parsed as reStructuredText.
Editing the Documentation¶
If you plan on editing the documentation pages (i.e. adding a tutorial or fixing an existing page), please visit the docs/ folder. The docs/ folder is structured as follows:
docs/
├── _static/ # Static files that persist through the build process
│ ├── css/custom.css # Custom css changes that are different from the default furo theme
│ └── ... # Images, favicons, etc.
├── usage/ # Usage reference guide for the ACI package
│ └── ...
├── setup.md # Installation build instructions
├── contributing.md # Contributing tab with instructions on how to contribute to the repo
├── conf.py # Settings related to extensions, themes, etc.
└── index.md # The "home" page
Please try to maintain the file structure as described above. All tabs with only a single page (i.e. background or contributing), should have their markdown file with in the docs/ folder. If the tab has or will have multiple pages (i.e. a tutorials tab), create a folder titled the same as that tab. To add pages, insert the name of the file without the .md extension within the table of contents inside index.md. Each folder should also contain an index.md used as the home page of that tab.
Markdown files are converted to reStructuredText by myst_parser which is used by the documentation package Sphinx. Both Markdown and reStructuredText have their advantages and disadvantages, myst_parser allows us to use the easy to understand markdown language but also compile the content down to something Sphinx understands. To see additional features of the myst_parser library, please visit their website.
Building the Documentation¶
There are multiple ways to build sphinx documentation. The easiest is using the Makefile or make.bat file provided directly in this repository. You will need to install all the necessary dependencies and build the html pages. To do that, run the following commands:
cd ACI
pip install -e .[docs] # Install the package with the necessary dependencies
cd docs
make clean html
To view the build, go to your browser, and open the index.html file located inside docs/build/html/.
sphinx-autobuild is also extremely easy to use and will automatically build the html pages when a change is made. See their PyPI page. TL;DR: pip install sphinx-autobuild and run sphinx-autobuild . build.