... | ... | @@ -5,4 +5,14 @@ In these files, the version numbers of the packages (dependencies) are pinned to |
|
|
|
|
|
However, for the users who simply wish to install and use miniff, only the minimum working version numbers of the bare minimum packages needed to use miniff are specified. This is done in setup.py. Strictly pinning the package version numbers may cause automatic downgrading of the version numbers of the other packages in the end user's system to ensure compatibility. This can be inconvenient to the end users who simply wish to use miniff.
|
|
|
|
|
|
It is a good practice to regularly update the version numbers (major and minor) in the requiremens.txt and environment.yml before they are too outdated. This can be accomplished via CI where miniff can be tested with newer versions of dependencies before finally updating their version numbers. |
|
|
\ No newline at end of file |
|
|
It is a good practice to regularly update the version numbers (major and minor) in the requiremens.txt and environment.yml before they are too outdated. This can be accomplished via CI where miniff can be tested with newer versions of dependencies before finally updating their version numbers.
|
|
|
|
|
|
## Documentation
|
|
|
|
|
|
The documentation for miniff is created using Sphinx and hosted on read the docs. [jupyter-sphinx](https://jupyter-sphinx.readthedocs.io/en/latest/) is used to embed code in the documentation. This allows one to aid the documentation with plots and results via embeddeding segments of statically executable code in the main text. The documentation for miniff is developed according to the documentation guidelines listed in the group Wiki.
|
|
|
|
|
|
### Read the Docs configuration
|
|
|
Upon each push to the master branch, read the docs builds the documentation at its end and updates it on the public URL. This is accomplished via a webhook that is automatically created when one imports the repository on read the docs for the first time. You can find general information on importing the documentation [here](https://docs.readthedocs.io/en/stable/intro/import-guide.html) and setting up the webhook [here](https://docs.readthedocs.io/en/stable/webhooks.html)
|
|
|
The dependencies required to build the documentation must be specified in a requirements.txt/environment.yml placed in docs/ directory. In the case of miniff, the dependencies to build the documentation also includes the dependencies to build and run the code that is embedded in the text. This includes miniff itself as one of the dependencies because the code segments in the documentation text imports miniff.
|
|
|
At the point of creating this requirements.txt file in docs/, miniff wasn't uploaded on PyPI yet, so the alternate option of specifying installing miniff via setup tools was chosen. This is accomplished by specifying setup tools as the installation method in .readthedocs.yml file and check marking the 'install as project' option in the advanced settings on the read the docs web dashboard.
|
|
|
|
|
|
\ No newline at end of file |