diff --git a/docs/conf.py b/docs/conf.py index f568add1b..332ac2c72 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -15,6 +15,8 @@ import sys import logging import setuptools +import subprocess +from string import Template if os.getenv("PROJ_LIB") is None or os.getenv("PROJ_LIB") == "PROJ_LIB": conda_file_dir = setuptools.__file__ @@ -117,6 +119,21 @@ # The full version, including alpha/beta/rc tags. release = __version__ +# Replace $variables in the .rst files if on a readthedocs worker +if "/home/docs/checkouts" in " ".join(sys.argv): + mss_search = subprocess.run(["conda", "search", "-c", "conda-forge", "mss"], stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, encoding="utf8").stdout + # mss_search is inside a code block, reflect indentation + mss_search = (" " * 3).join([line for line in mss_search.splitlines(True) if line.startswith("mss ")][-2:]) + + for file in os.listdir(): + if file.endswith(".rst"): + with open(file, "r") as rst: + content = Template(rst.read()) + with open(file, "w") as rst: + rst.write(content.safe_substitute(mss_version=version[:-1] if version[-1] == "." else version, + mss_search=mss_search)) + # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # diff --git a/docs/development.rst b/docs/development.rst index b3e834d9e..86ea1920c 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -1,5 +1,40 @@ .. _development: +=========== +Development +=========== + +This chapter will get you started with MSS development. + +MSS is written in Python. + +Once a stable release is published we do only bug fixes in stable and release regulary +new minor versions. If a fix needs a API change or it is likly more a new feature you have +to make a pull request to the develop branch. Documentation of changes is done by using our +`issue tracker `_. + +When it is ready the developer version becomes the next stable. + + +The stable version of MSS is tracked on `BLACK DUCK Open Hub `_ + + +Style guide +~~~~~~~~~~~~~~~~ + +We generally follow flake8, with 120 columns instead of 79. + +Output and Logging +~~~~~~~~~~~~~~~~~~~~~~~~~ + +When writing logger calls, always use correct log level (debug only for debugging, info for informative messages, +warning for warnings, error for errors, critical for critical errors/states). + +Setting Up a Local Environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Requirements +------------ 1. System requirements @@ -7,30 +42,27 @@ | Operating System : Any (Windows / Linux / Mac). 2. Software requirement + | Python | `Additional Requirements `_ - + 3. Skill set + | Knowledge of git & github | python -============================ -Setting Up local Environement -============================ - -============================ Forking the Repo -============================ -1. Firstly you have to make your own copy of project. For that you have to fork the repository. You can find the fork button on the top-right side of the browser window. +---------------- + +1. Firstly you have to make your own copy of project. For that you have to fork the repository. You can find the fork button on the top-right side of the browser window. 2. Kindly wait till it gets forked. 3. After that copy will look like */MSS* forked from *Open-MSS/MSS*. -============================ Cloning the Repo -============================ +---------------- 1. Now you have your own copy of project. Here you have to start your work. @@ -46,9 +78,10 @@ Cloning the Repo or simply head over here for `cloning a repository `_ -============================ -Setting up remote : -============================ +7. Add the path of your local cloned mss directory to $PYTHONPATH. + +Setting up a git remote +----------------------- 1. Now you have to set up remote repositories @@ -74,64 +107,11 @@ Setting up remote : upstream ``https://github.com/Open-MSS/MSS.git`` (push) - -============================ -How to Report Bugs: -============================ -Please open a new issue in the appropriate GitHub repository `here `_ with steps to reproduce the problem you're experiencing. - -Be sure to include as much information including screenshots, text output, and both your expected and actual results. - -============================ -How to Request Enhancements: -============================ -First, please refer to the applicable `GitHub repository `_ and search `the repository's GitHub issues `_ to make sure your idea has not been (or is not still) considered. - -Then, please `create a new issue `_ in the GitHub repository describing your enhancement. - -Be sure to include as much detail as possible including step-by-step descriptions, specific examples, screenshots or mockups, and reasoning for why the enhancement might be worthwhile. - -============================ -Development -============================ - -This chapter will get you started with MSS development. - -MSS is written in Python. - -Once a stable release is published we do only bug fixes in stable and release regulary -new minor versions. If a fix needs a API change or it is likly more a new feature you have -to make a pull request to the develop branch. Documentation of changes is done by using our -`issue tracker `_. - -When it is ready the developer version becomes the next stable. - - -The stable version of MSS is tracked on `BLACK DUCK Open Hub `_ - - -Style guide -~~~~~~~~~~~~~~~~ - -We generally follow flake8, with 120 columns instead of 79. - -Output and Logging -~~~~~~~~~~~~~~~~~~~~~~~~~ - -When writing logger calls, always use correct log level (debug only for debugging, info for informative messages, -warning for warnings, error for errors, critical for critical errors/states). - -Setup a development environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you want to contribute make a fork on github of `MSS `_. - -In the mss package is some demodata included. The default where this is stored is $HOME/mss. Your clone of the -MSS repository needs a different folder, e.g. workspace/mss. Avoid to mix data and source. +Installing dependencies +----------------------- MSS is based on the software of the conda-forge channel located, so we have to add this channel to the default:: - $ conda config --add channels conda-forge Your content of the .condarc config file should have conda-forge on top:: @@ -145,26 +125,54 @@ Create an environment and install the whole mss package dependencies then remove $ conda create -n mssdev mamba $ conda activate mssdev - $ mamba install mss=4.0.1 --only-deps + $ mamba install mss=$mss_version --only-deps You can also use conda to install mss, but mamba is a way faster. Compare versions used in the meta.yaml between stable and develop branch and apply needed changes. -Add the path of your local cloned mss directory to $PYTHONPATH. +Pushing your changes +-------------------- -For developer we provide additional packages for running tests, activate your env and run:: +1. Now you have made the changes, tested them and built them. So now it's time to push them. +2. Goto your terminal and type git status and hit enter, this will show your changes from the files +3. Then type in git add and hit enter, this will add all the files to staging area +4. Commit the changes by ``git commit -m ""`` and hit enter. +5. Now push your branch to your fork by ``git push origin `` and hit enter. - $ mamba install --file requirements.d/development.txt -On linux install the `conda package pyvirtualdisplay` and `xvfb` from your linux package manager. -This is used to run tests on a virtual display. -If you don't want tests redirected to the xvfb display just setup an environment variable:: +Creating a pull request +----------------------- - $ export TESTS_VISIBLE=TRUE +By this time you can see a message on your github fork as your fork is ahead of Open-MSS:develop by of commits and also you can see a button called Compare and pull request. + +Click on Compare and pull request button. + +You will see a template. + +Fill out the template completely by describing your change, cause of change, issue getting fixed etc. + +After filling the template completely click on Pull request + +How to Report Bugs +~~~~~~~~~~~~~~~~~~ + +Please open a new issue in the appropriate GitHub repository `here `_ with steps to reproduce the problem you're experiencing. + +Be sure to include as much information including screenshots, text output, and both your expected and actual results. + +How to Request Enhancements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +First, please refer to the applicable `GitHub repository `_ and search `the repository's GitHub issues `_ to make sure your idea has not been (or is not still) considered. + +Then, please `create a new issue `_ in the GitHub repository describing your enhancement. + +Be sure to include as much detail as possible including step-by-step descriptions, specific examples, screenshots or mockups, and reasoning for why the enhancement might be worthwhile. Setup demodata ~~~~~~~~~~~~~~ +In the mss package is some demodata included. The default where this is stored is $HOME/mss. Your clone of the +MSS repository needs a different folder, e.g. workspace/mss. Avoid to mix data and source. :ref:`demodata` is provided by executing:: @@ -196,6 +204,15 @@ Now you can use the MSS desktop application to connect to it using the Mscolab w Running tests ~~~~~~~~~~~~~~~~~~~ +For developers we provide additional packages for running tests, activate your env and run:: + + $ mamba install --file requirements.d/development.txt + +On linux install the `conda package pyvirtualdisplay` and `xvfb` from your linux package manager. +This is used to run tests on a virtual display. +If you don't want tests redirected to the xvfb display just setup an environment variable:: + + $ export TESTS_VISIBLE=TRUE We have implemented demodata as data base for testing. On first call of pytest a set of demodata becomes stored in a /tmp/mss* folder. If you have installed gitpython a postfix of the revision head is added. @@ -282,7 +299,7 @@ If you don't have a stable branch, create one first or change to that branch:: Merging stable into develop ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Bug fixes we have done in stable we need to merge regulary into develop too:: +Bug fixes we have done in stable we need to merge regulary into develop too:: git checkout stable git pull git@github.com:Open-MSS/MSS.git stable @@ -347,29 +364,3 @@ Publish on Conda Forge * rerender the feedstock by conda smithy * send a pull request * maintainer will merge if there is no error - - -============================ -Pushing your changes: -============================ - -1. Now you have made the changes, tested them and built them. So now it's time to push them. -2. Goto your terminal and type git status and hit enter, this will show your changes from the files -3. Then type in git add and hit enter, this will add all the files to staging area -4. Commit the changes by ``git commit -m ""`` and hit enter. -5. Now push your branch to your fork by ``git push origin `` and hit enter. - - -============================ -Creating a pull request: -============================ -By this time you can see a message on your github fork as your fork is ahead of Open-MSS:develop by of commits and also you can see a button called Compare and pull request. - -Click on Compare and pull request button. - -You will see a template. - -Fill out the template completely by describing your change, cause of change, issue getting fixed etc. - -After filling the template completely click on Pull request - diff --git a/docs/installation.rst b/docs/installation.rst index 4b6bb26ac..45a56f5b5 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -56,7 +56,7 @@ leave out the 'source' here and below). :: $ conda create -n mssenv mamba $ conda activate mssenv - (mssenv) $ mamba install mss=4.0.1 python + (mssenv) $ mamba install mss=$mss_version python You need to reactivate after the installation once the environment to setup all needed enironment @@ -82,8 +82,7 @@ search for MSS what you can get :: (mssenv) $ mamba search mss ... - mss 4.0.1 py38h578d9bd_0 conda-forge - mss 4.0.1 py39hf3d152e_0 conda-forge + $mss_search compare what you have installed :: @@ -93,9 +92,9 @@ compare what you have installed :: We have reports that often an update suceeds by using the install option and the new version number, -in this example 4.0.1 and python as second option :: +in this example $mss_version and python as second option :: - (mssenv) $ mamba install mss=4.0.1 python + (mssenv) $ mamba install mss=$mss_version python All attemmpts show what you get if you continue. **Continue only if you get what you want.** @@ -123,7 +122,7 @@ We suggest to create a mss user. * login again or export PATH="/home/mss/miniconda3/bin:$PATH" * conda create -n mssenv mamba * conda activate mssenv -* mamba install mss=4.0.1 python +* mamba install mss=$mss_version python For a simple test you could start the builtin standalone *mswms* and *mscolab* server::