diff --git a/.buildinfo b/.buildinfo new file mode 100644 index 0000000..3cc786a --- /dev/null +++ b/.buildinfo @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file records the configuration used when building these files. When it is not found, a full rebuild will be done. +config: 7a827e5f8e3d7235ec3768d8ee6ec5e5 +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/_modules/index.html b/_modules/index.html new file mode 100644 index 0000000..6c3c767 --- /dev/null +++ b/_modules/index.html @@ -0,0 +1,103 @@ + + + +
+ + +
+"""
+This is a skeleton file that can serve as a starting point for a Python
+console script. To run this script uncomment the following lines in the
+``[options.entry_points]`` section in ``setup.cfg``::
+
+ console_scripts =
+ fibonacci = rheed_learn.skeleton:run
+
+Then run ``pip install .`` (or ``pip install -e .`` for editable mode)
+which will install the command ``fibonacci`` inside your current environment.
+
+Besides console scripts, the header (i.e. until ``_logger``...) of this file can
+also be used as template for Python modules.
+
+Note:
+ This file can be renamed depending on your needs or safely removed if not needed.
+
+References:
+ - https://setuptools.pypa.io/en/latest/userguide/entry_point.html
+ - https://pip.pypa.io/en/stable/reference/pip_install
+"""
+
+import argparse
+import logging
+import sys
+
+from rheed_learn import __version__
+
+__author__ = "Yichen Guo"
+__copyright__ = "Yichen Guo"
+__license__ = "MIT"
+
+_logger = logging.getLogger(__name__)
+
+
+# ---- Python API ----
+# The functions defined in this section can be imported by users in their
+# Python scripts/interactive interpreter, e.g. via
+# `from rheed_learn.skeleton import fib`,
+# when using this Python module as a library.
+
+
+
+[docs]
+def fib(n):
+ """Fibonacci example function
+
+ Args:
+ n (int): integer
+
+ Returns:
+ int: n-th Fibonacci number
+ """
+ assert n > 0
+ a, b = 1, 1
+ for _i in range(n - 1):
+ a, b = b, a + b
+ return a
+
+
+
+# ---- CLI ----
+# The functions defined in this section are wrappers around the main Python
+# API allowing them to be called directly from the terminal as a CLI
+# executable/script.
+
+
+
+[docs]
+def parse_args(args):
+ """Parse command line parameters
+
+ Args:
+ args (List[str]): command line parameters as list of strings
+ (for example ``["--help"]``).
+
+ Returns:
+ :obj:`argparse.Namespace`: command line parameters namespace
+ """
+ parser = argparse.ArgumentParser(description="Just a Fibonacci demonstration")
+ parser.add_argument(
+ "--version",
+ action="version",
+ version=f"RHEED-Learn {__version__}",
+ )
+ parser.add_argument(dest="n", help="n-th Fibonacci number", type=int, metavar="INT")
+ parser.add_argument(
+ "-v",
+ "--verbose",
+ dest="loglevel",
+ help="set loglevel to INFO",
+ action="store_const",
+ const=logging.INFO,
+ )
+ parser.add_argument(
+ "-vv",
+ "--very-verbose",
+ dest="loglevel",
+ help="set loglevel to DEBUG",
+ action="store_const",
+ const=logging.DEBUG,
+ )
+ return parser.parse_args(args)
+
+
+
+
+[docs]
+def setup_logging(loglevel):
+ """Setup basic logging
+
+ Args:
+ loglevel (int): minimum loglevel for emitting messages
+ """
+ logformat = "[%(asctime)s] %(levelname)s:%(name)s:%(message)s"
+ logging.basicConfig(
+ level=loglevel, stream=sys.stdout, format=logformat, datefmt="%Y-%m-%d %H:%M:%S"
+ )
+
+
+
+
+[docs]
+def main(args):
+ """Wrapper allowing :func:`fib` to be called with string arguments in a CLI fashion
+
+ Instead of returning the value from :func:`fib`, it prints the result to the
+ ``stdout`` in a nicely formatted message.
+
+ Args:
+ args (List[str]): command line parameters as list of strings
+ (for example ``["--verbose", "42"]``).
+ """
+ args = parse_args(args)
+ setup_logging(args.loglevel)
+ _logger.debug("Starting crazy calculations...")
+ print(f"The {args.n}-th Fibonacci number is {fib(args.n)}")
+ _logger.info("Script ends here")
+
+
+
+
+[docs]
+def run():
+ """Calls :func:`main` passing the CLI arguments extracted from :obj:`sys.argv`
+
+ This function can be used as entry point to create console scripts with setuptools.
+ """
+ main(sys.argv[1:])
+
+
+
+if __name__ == "__main__":
+ # ^ This is a guard statement that will prevent the following code from
+ # being executed in the case someone imports this file instead of
+ # executing it as a script.
+ # https://docs.python.org/3/library/__main__.html
+
+ # After installing your project with pip, users can also run your Python
+ # modules as scripts via the ``-m`` flag, as defined in PEP 338::
+ #
+ # python -m rheed_learn.skeleton 42
+ #
+ run()
+
' + + '' + + _("Hide Search Matches") + + "
" + ) + ); + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords: () => { + document + .querySelectorAll("#searchbox .highlight-link") + .forEach((el) => el.remove()); + document + .querySelectorAll("span.highlighted") + .forEach((el) => el.classList.remove("highlighted")); + localStorage.removeItem("sphinx_highlight_terms") + }, + + initEscapeListener: () => { + // only install a listener if it is really needed + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; + if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { + SphinxHighlight.hideSearchWords(); + event.preventDefault(); + } + }); + }, +}; + +_ready(() => { + /* Do not call highlightSearchWords() when we are on the search page. + * It will highlight words from the *previous* search query. + */ + if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); + SphinxHighlight.initEscapeListener(); +}); diff --git a/api/modules.html b/api/modules.html new file mode 100644 index 0000000..449cd11 --- /dev/null +++ b/api/modules.html @@ -0,0 +1,132 @@ + + + + + + + +This is a skeleton file that can serve as a starting point for a Python
+console script. To run this script uncomment the following lines in the
+[options.entry_points]
section in setup.cfg
:
console_scripts =
+ fibonacci = rheed_learn.skeleton:run
+
Then run pip install .
(or pip install -e .
for editable mode)
+which will install the command fibonacci
inside your current environment.
Besides console scripts, the header (i.e. until _logger
…) of this file can
+also be used as template for Python modules.
Note
+This file can be renamed depending on your needs or safely removed if not needed.
+References
+ + + +Wrapper allowing fib()
to be called with string arguments in a CLI fashion
Instead of returning the value from fib()
, it prints the result to the
+stdout
in a nicely formatted message.
args (List[str]) – command line parameters as list of strings
+(for example ["--verbose", "42"]
).
Parse command line parameters
+args (List[str]) – command line parameters as list of strings
+(for example ["--help"]
).
command line parameters namespace
+Yichen Guo <yig319@lehigh.edu>
Welcome to RHEED-Learn
contributor’s guide.
This document focuses on getting any potential contributor familiarized +with the development processes, but other kinds of contributions are also +appreciated.
+If you are new to using git or have never collaborated in a project previously, +please have a look at contribution-guide.org. Other resources are also +listed in the excellent guide created by FreeCodeCamp [1].
+Please notice, all users and contributors are expected to be open, +considerate, reasonable, and respectful. When in doubt, Python Software +Foundation’s Code of Conduct is a good reference in terms of behavior +guidelines.
+If you experience bugs or general issues with RHEED-Learn
, please have a look
+on the issue tracker. If you don’t see anything useful there, please feel
+free to fire an issue report.
Tip
+Please don’t forget to include the closed issues in your search. +Sometimes a solution was already reported, and the problem is considered +solved.
+New issue reports should include information about your programming environment +(e.g., operating system, Python version) and steps to reproduce the problem. +Please try also to simplify the reproduction steps to a very minimal example +that still illustrates the problem you are facing. By removing other factors, +you help us to identify the root cause of the issue.
+You can help improve RHEED-Learn
docs by making them more readable and coherent, or
+by adding missing information and correcting mistakes.
RHEED-Learn
documentation uses Sphinx as its main documentation compiler.
+This means that the docs are kept in the same repository as the project code, and
+that any documentation update is done in the same way was a code contribution.
When working on documentation changes in your local machine, you can
+compile them using tox
:
tox -e docs
+
and use Python’s built-in web server for a preview in your web browser
+(http://localhost:8000
):
python3 -m http.server --directory 'docs/_build/html'
+
Before you work on any non-trivial code contribution it’s best to first create +a report in the issue tracker to start a discussion on the subject. +This often provides additional considerations and avoids unnecessary work.
+Before you start coding, we recommend creating an isolated virtual
+environment to avoid any problems with your installed Python packages.
+This can easily be done via either virtualenv
:
virtualenv <PATH TO VENV>
+source <PATH TO VENV>/bin/activate
+
or Miniconda:
+conda create -n RHEED-Learn python=3 six virtualenv pytest pytest-cov
+conda activate RHEED-Learn
+
Create an user account on GitHub if you do not already have one.
Fork the project repository: click on the Fork button near the top of the +page. This creates a copy of the code under your account on GitHub.
Clone this copy to your local disk:
+git clone git@github.com:YourLogin/RHEED-Learn.git
+cd RHEED-Learn
+
You should run:
+pip install -U pip setuptools -e .
+
to be able to import the package under development in the Python REPL.
+Install pre-commit
:
pip install pre-commit
+pre-commit install
+
RHEED-Learn
comes with a lot of hooks configured to automatically help the
+developer to check the code being written.
Create a branch to hold your changes:
+git checkout -b my-feature
+
and start making changes. Never work on the main branch!
+Start your work on this branch. Don’t forget to add docstrings to new +functions, modules and classes, especially if they are part of public APIs.
Add yourself to the list of contributors in AUTHORS.rst
.
When you’re done editing, do:
+git add <MODIFIED FILES>
+git commit
+
to record your changes in git.
+Please make sure to see the validation messages from pre-commit
and fix
+any eventual issues.
+This should automatically use flake8/black to check/fix the code style
+in a way that is compatible with the project.
Important
+Don’t forget to add unit tests and documentation in case your +contribution adds an additional feature and is not just a bugfix.
+Moreover, writing a descriptive commit message is highly recommended. +In case of doubt, you can check the commit history with:
+git log --graph --decorate --pretty=oneline --abbrev-commit --all
+
to look for recurring communication patterns.
+Please check that your changes don’t break any unit tests with:
+tox
+
(after having installed tox
with pip install tox
or pipx
).
You can also use tox
to run several other pre-configured tasks in the
+repository. Try tox -av
to see a list of the available checks.
If everything works fine, push your local branch to GitHub with:
+git push -u origin my-feature
+
Go to the web page of your fork and click “Create pull request” +to send your changes for review.
+The following tips can be used when facing problems to build or test the +package:
+Make sure to fetch all the tags from the upstream repository.
+The command git describe --abbrev=0 --tags
should return the version you
+are expecting. If you are trying to run CI scripts in a fork repository,
+make sure to push all the tags.
+You can also try to remove all the egg files or the complete egg folder, i.e.,
+.eggs
, as well as the *.egg-info
folders in the src
folder or
+potentially in the root of your project.
Sometimes tox
misses out when new dependencies are added, especially to
+setup.cfg
and docs/requirements.txt
. If you find any problems with
+missing dependencies when running a command with tox
, try to recreate the
+tox
environment using the -r
flag. For example, instead of:
tox -e docs
+
Try running:
+tox -r -e docs
+
Make sure to have a reliable tox
installation that uses the correct
+Python version (e.g., 3.7+). When in doubt you can run:
tox --version
+# OR
+which tox
+
If you have trouble and are seeing weird errors upon running tox
, you can
+also try to create a dedicated virtual environment with a tox
binary
+freshly installed. For example:
virtualenv .venv
+source .venv/bin/activate
+.venv/bin/pip install tox
+.venv/bin/tox -e all
+
Pytest can drop you in an interactive session in the case an error occurs.
+In order to do that you need to pass a --pdb
option (for example by
+running tox -- -k <NAME OF THE FALLING TEST> --pdb
).
+You can also setup breakpoints manually instead of using the --pdb
option.
If you are part of the group of maintainers and have correct user permissions
+on PyPI, the following steps can be used to release a new version for
+RHEED-Learn
:
Make sure all unit tests are successful.
Tag the current commit on the main branch with a release tag, e.g., v1.2.3
.
Push the new tag to the upstream repository, e.g., git push upstream v1.2.3
Clean up the dist
and build
folders with tox -e clean
+(or rm -rf dist build
)
+to avoid confusion with old builds and Sphinx docs.
Run tox -e build
and check that the files in dist
have
+the correct version (no .dirty
or git hash) according to the git tag.
+Also check the sizes of the distributions, if they are too big (e.g., >
+500KB), unwanted clutter may have been accidentally included.
Run tox -e publish -- --repository pypi
and check that everything was
+uploaded to PyPI correctly.
+ |
|
+
+ |
|
+
|
+
+ |
This is the documentation of RHEED-Learn.
+Note
+This is the main page of your project’s Sphinx documentation.
+It is formatted in reStructuredText. Add additional pages
+by creating rst-files in docs
and adding them to the toctree below.
+Use then references in order to link them from this page, e.g.
+Contributors and Changelog.
It is also possible to refer to the documentation of other Python packages
+with the Python domain syntax. By default you can reference the
+documentation of Sphinx, Python, NumPy, SciPy, matplotlib,
+Pandas, Scikit-Learn. You can add more by extending the
+intersphinx_mapping
in your Sphinx’s conf.py
.
The pretty useful extension autodoc is activated by default and lets +you include documentation from docstrings. Docstrings can be written in +Google style (recommended!), NumPy style and classical style.
+The MIT License (MIT)
+Copyright (c) 2024 Yichen Guo
+Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the “Software”), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE.
++ r | ||
+ |
+ rheed_learn | + |
+ |
+ rheed_learn.skeleton | + |
++Add a short description here!
+
A longer description of your project goes here…
+This project has been set up using PyScaffold 4.6. For details and usage +information on PyScaffold see https://pyscaffold.org/.
++ Searching for multiple words only shows matches that contain + all words. +
+ + + + + + + + +