From 9c38e069ea2a5a43ec1c38b44754e433b66d6f2a Mon Sep 17 00:00:00 2001 From: Andrey Zhdanov Date: Tue, 1 Aug 2023 11:35:01 +0300 Subject: [PATCH] docs updated --- docs/install_win.rst | 18 +++++++++++------- docs/techdoc.rst | 23 ++++++++++++++--------- 2 files changed, 25 insertions(+), 16 deletions(-) diff --git a/docs/install_win.rst b/docs/install_win.rst index 89380e4f..158edb2d 100644 --- a/docs/install_win.rst +++ b/docs/install_win.rst @@ -82,17 +82,21 @@ In the activated environment, type An icon should appear on your desktop, which will activate the correct environment and start the GUI. -Updating the package --------------------- - -To update, give the command +If you get an error message running the above command (this might happen, +for example, if your computer has restrictions set up by your organization's +IT department), you can try running :: - pip install --upgrade https://github.com/NCH-Motion-Laboratory/gaitutils/archive/master.zip + python -c "from gaitutils.envutils import _make_gaitutils_shortcut; _make_gaitutils_shortcut()" + +instead. + +Updating the package +-------------------- -Occassionally it may be beneficial or necessary to upgrade the dependencies as -well. Unfortunately, there's currently no simple way to do this. The best way +Unfortunately, there's currently no simple way to perform an upgrade +in a safe and reliable fashion. The best way may be to simply delete the whole environment with :: diff --git a/docs/techdoc.rst b/docs/techdoc.rst index eee8b2f9..ea9e5ade 100644 --- a/docs/techdoc.rst +++ b/docs/techdoc.rst @@ -67,12 +67,17 @@ latest GitHub master branch. It can then be updated with ``pip``. However, developers and advanced users will wish to install in "git mode" instead (i.e. run the package directly from a cloned repository). This can be done as follows: -- clone the repository from GitHub -- perform a normal install using the conda environment -- activate the new environment -- remove the pip install using ``pip uninstall gaitutils`` -- change directory to root of cloned repository -- run ``pip install -e .`` (previously ``python setup.py develop`` which is now deprecated) +- Clone the repository from GitHub +- Perform a normal install using the conda environment. You may want to use the + development version of the conda environment specification -- ``environment_dev.yml`` + for Windows or ``environment_linux_dev.yml`` for Linux. The development versions + of the specification do not specify package versions. This means that conda will try + to install the most recent versions of all the package requirements, potentially + leading to problems. +- Activate the new environment +- Remove the pip install using ``pip uninstall gaitutils`` +- Change directory to root of cloned repository +- Run ``pip install -e .`` (previously ``python setup.py develop`` which is now deprecated) Desktop shortcuts ----------------- @@ -93,10 +98,10 @@ updated. Locally, the documentation can be recreated by running :: - ./make.bat html + sphinx-build -b html docs docs-html -in the ``docs`` directory. The resulting html documentation will appear in -``docs/_build/html``. +in the project's root directory. The resulting html documentation will appear in +``docs-html`` directory. To build the documentation, you need to have the ``sphinx_rtd_theme`` package installed. It can be installed using ``pip``.