Skip to content

Latest commit

 

History

History
123 lines (121 loc) · 3.83 KB

DEVELOPMENT.md

File metadata and controls

123 lines (121 loc) · 3.83 KB

Development

This is an example of a workflow that describes the development process.

  • Clone EasyDiffractionLib repository 
    git clone https://github.com/EasyScience/EasyDiffractionLib
  • Go to the cloned directory 
    cd EasyDiffractionLib
  • Checkout/switch to the develop branch 
    git checkout develop
  • Create a new branch from the current one 
    git checkout -b new-feature
  • Create Python environment and activate it 
    python3 -m venv .venv
source .venv/bin/activate
  • Upgrade PIP - package installer for Python 
    python -m pip install --upgrade pip
  • Install easydiffraction from root with dev extras for development, charts extras for Jupyter notebooks and docs extras for building documentation 
    pip install '.[dev,charts,docs]'
  • Make changes in the code 
    ...
  • Check the validity of pyproject.toml 
    validate-pyproject pyproject.toml
  • Run Ruff - Python linter and code formatter (configuration is in pyproject.toml)
    Linting (overwriting files) 
    ruff check . --fix
    Formatting (overwriting files) 
    ruff format .
  • Install and run Prettier - code formatter for Markdown, YAML, TOML, etc. files (configuration in prettierrc.toml)
    Formatting (overwriting files) 
    npm install prettier prettier-plugin-toml --save-dev --save-exact
npx prettier . --write --config=prettierrc.toml
  • Run python tests 
    pytest tests/ --color=yes -n auto
  • Clear all Jupyter notebooks output (Only those that were changed!). Replace examples/*.ipynb with the path to the notebook(s) you want to clear 
    jupyter nbconvert --clear-output --inplace examples/*.ipynb
  • Run nbQA - Jupyter notebooks quality assurance package 
    nbqa ruff examples/ --fix
  • Run Jupyter notebooks as tests 
    pytest --nbmake examples/ --ignore-glob='examples/*emcee*' --nbmake-timeout=300 --color=yes -n=auto
  • Add extra files to build documentation (from ../assets-docs/ and ../assets-branding/ directories) 
    cp -R ../assets-docs/docs/assets/ docs/assets/
cp -R ../assets-docs/includes/ includes/
cp -R ../assets-docs/overrides/ overrides/
mkdir -p docs/assets/images/
cp ../assets-branding/easydiffraction/logos/ed-logo-2_dark.svg docs/assets/images/
cp ../assets-branding/easydiffraction/logos/ed-logo-2_light.svg docs/assets/images/
<!-- cp ../assets-branding/easydiffraction/logos/edl-logo_dark.svg docs/assets/images/logo_dark.svg
cp ../assets-branding/easydiffraction/logos/edl-logo_light.svg docs/assets/images/logo_light.svg -->
cp ../assets-branding/easydiffraction/icons/ed-icon_256x256.png docs/assets/images/favicon.png
mkdir -p overrides/.icons/
cp ../assets-branding/easydiffraction/icons/ed-icon_bw.svg overrides/.icons/easydiffraction.svg
cp ../assets-branding/easyscience-org/icons/eso-icon_bw.svg overrides/.icons/easyscience.svg
cp -R examples/ docs/examples/
cat ../assets-docs/mkdocs.yml docs/mkdocs.yml > mkdocs.yml
  • Build documentation with MkDocs - static site generator 
    export JUPYTER_PLATFORM_DIRS=1
mkdocs serve
  • Test the documentation locally (built in the site/ directory). E.g., on macOS, open the site in the default browser via the terminal 
    open http://127.0.0.1:8000
  • Clean up after building documentation 
    rm -rf site/
rm -rf docs/assets/
rm -rf includes/
rm -rf overrides/
rm -rf docs/examples/
rm -rf node_modules/
rm mkdocs.yml
rm package-lock.json
rm package.json
  • Commit changes 
    git add .
git commit -m "Add new feature"
  • Push the new branch to a remote repository 
    git push -u origin new-feature