Skip to content

Commit

Permalink
Merge pull request #1 from rdnfn/docs
Browse files Browse the repository at this point in the history 
Docs
  • Loading branch information
@rdnfn
rdnfn authored Jan 9, 2022
2 parents 87f6b87 + 9086e96 commit d1b8d74
Show file tree
Hide file tree
Showing 6 changed files with 69 additions and 87 deletions.
10 changes: 7 additions & 3 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,17 +11,19 @@

</p>

.. start-in-sphinx-docs
.. image:: https://img.shields.io/pypi/v/beobench.svg
:target: https://pypi.python.org/pypi/beobench

.. image:: https://img.shields.io/travis/rdnfn/beobench.svg
:target: https://travis-ci.com/rdnfn/beobench

.. image:: https://readthedocs.org/projects/beobench/badge/?version=latest
:target: https://beobench.readthedocs.io/en/latest/?version=latest
:alt: Documentation Status

.. image:: https://img.shields.io/badge/License-MIT-blue.svg
:target: https://opensource.org/licenses/MIT
:alt: License

A toolbox for benchmarking reinforcement learning (RL) algorithms on building energy optimisation (BEO) problems. Beobench does not replace existing libraries defining BEO problems (such as `BOPTEST <https://github.com/ibpsa/project1-boptest>`_) — instead it makes working with them easier.

Features
Expand All @@ -34,6 +36,8 @@ Features

.. _Weights and Biases: https://wandb.ai/

.. end-in-sphinx-docs
Documentation
-------------
https://beobench.readthedocs.io
Expand Down
5 changes: 5 additions & 0 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -163,4 +163,9 @@
"logo_name": False, # logo_only for alabaster theme
"display_version": True,
"logo": "/beobench_logo.png",
"github_repo": "beobench",
"github_user": "rdnfn",
"github_button": True,
"github_count": False,
"github_type": "star",
}
9 changes: 6 additions & 3 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,14 @@ Welcome to beobench's documentation!
======================================

.. include:: ../README.rst
:start-line: 14
:start-after: start-in-sphinx-docs
:end-before: end-in-sphinx-docs

Contents
--------

.. toctree::
:maxdepth: 2
:caption: Contents:

installation
usage
Expand All @@ -16,7 +19,7 @@ Welcome to beobench's documentation!
history

Indices and tables
==================
------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
72 changes: 50 additions & 22 deletions docs/installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,47 +5,75 @@ Installation
============


Stable release
--------------
Recommended method
------------------

To install beobench, run this command in your terminal:

.. code-block:: console
$ pip install beobench
pip install git+https://github.com/rdnfn/beobench
This is the preferred method to install beobench, as it will always install the most recent stable release.
Additionally, it is necessary to have `docker <https://www.docker.com/get-started>`_ installed on the machine.

If you don't have `pip`_ installed, this `Python installation guide`_ can guide
you through the process.
.. This is the preferred method to install beobench, as it will always install the most recent stable release.
.. _pip: https://pip.pypa.io
.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
From sources
------------
The sources for beobench can be downloaded from the `Github repo`_.
Development environment
-----------------------

You can either clone the public repository:
Requirements
^^^^^^^^^^^^^^^^^^

.. code-block:: console
Beobench uses `vscode dev containers <https://code.visualstudio.com/docs/remote/containers-tutorial>`_ for its development environment. The installation has the following pre-requisites on the local machine:

$ git clone git://github.com/rdnfn/beobench
1. `Docker <https://www.docker.com/get-started>`_
2. `Visual Studio Code (vscode) <https://code.visualstudio.com/>`_
3. `vscode remote extension pack <https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack>`_

Or download the `tarball`_:
Additionally, for remote development, the remote machine must have docker installed.

.. code-block:: console

$ curl -OJL https://github.com/rdnfn/beobench/tarball/master
Local development
^^^^^^^^^^^^^^^^^^

Once you have a copy of the source, you can install it with:

.. code-block:: console
1. Clone the repo locally to your machine using

.. code-block::
git clone git@github.com:rdnfn/beobench.git
2. Open the git repo folder in vscode
3. Inside vscode, open the command palette (shortcut is ``shift`` + ``cmd`` + ``P`` on macos), and use the ``Remote-containers: open folder in container`` command. Select the ``beobench`` repo in the pop-up window (NOT the ``beobench`` folder inside the repo).

This should have opened a new vscode window running in the docker dev container -- once the dev container is ready you're done! (Note: this gets faster after the first docker build)


Remote development
^^^^^^^^^^^^^^^^^^

It may be desireable to run your dev container on a remote machine. In order to do this you need to follow the following steps:

1. Follow all the instructions for local development above (apart from the final step 3).
2. Clone the repo to your *remote* machine.
3. In the cloned repo on your local machine, in ``.devcontainer/devcontainer.json`` replace the line

.. code-block::
"workspaceMount": "source=/home/rdnfn-docker/main/repos/github/beobench/,target=/workspace,type=bind,consistency=cached"
with

.. code-block::
"workspaceMount": "source=<PATH_TO_CLONED_REPO>,target=/workspace,type=bind,consistency=cached"
$ python setup.py install
where ``PATH_TO_CLONED_REPO`` is the path to your repo on the remote machine.

4. Create a docker context on your local machine that connects to docker on your remote machine (`See the instructions here <https://stackoverflow.com/a/63814363>`_).
5. Use the ``Remote-containers: open folder in container`` command and select the ``beobench`` repo in the pop-up window (NOT the ``beobench`` folder inside the repo).

.. _Github repo: https://github.com/rdnfn/beobench
.. _tarball: https://github.com/rdnfn/beobench/tarball/master
1 change: 0 additions & 1 deletion docs/readme.rst
View file

This file was deleted.

59 changes: 1 addition & 58 deletions docs/usage.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,61 +4,4 @@ Usage

To use beobench in a project::

import beobench


Development environment
-----------------------

Requirements
^^^^^^^^^^^^^^^^^^

Beobench uses `vscode dev containers <https://code.visualstudio.com/docs/remote/containers-tutorial>`_ for its development environment. The installation has the following pre-requisites on the local machine:

1. `Docker <https://www.docker.com/get-started>`_
2. `Visual Studio Code (vscode) <https://code.visualstudio.com/>`_
3. `vscode remote extension pack <https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack>`_

Additionally, for remote development, the remote machine must have docker installed.


Local development
^^^^^^^^^^^^^^^^^^


1. Clone the repo locally to your machine using

.. code-block::
git clone git@github.com:rdnfn/beobench.git
2. Open the git repo folder in vscode
3. Inside vscode, open the command palette (shortcut is ``shift`` + ``cmd`` + ``P`` on macos), and use the ``Remote-containers: open folder in container`` command. Select the ``beobench`` repo in the pop-up window (NOT the ``beobench`` folder inside the repo).

This should have opened a new vscode window running in the docker dev container -- once the dev container is ready you're done! (Note: this gets faster after the first docker build)


Remote development
^^^^^^^^^^^^^^^^^^

It may be desireable to run your dev container on a remote machine. In order to do this you need to follow the following steps:

1. Follow all the instructions for local development above (apart from the final step 3).
2. Clone the repo to your *remote* machine.
3. In the cloned repo on your local machine, in ``.devcontainer/devcontainer.json`` replace the line

.. code-block::
"workspaceMount": "source=/home/rdnfn-docker/main/repos/github/beobench/,target=/workspace,type=bind,consistency=cached"
with

.. code-block::
"workspaceMount": "source=<PATH_TO_CLONED_REPO>,target=/workspace,type=bind,consistency=cached"
where ``PATH_TO_CLONED_REPO`` is the path to your repo on the remote machine.

4. Create a docker context on your local machine that connects to docker on your remote machine (`See the instructions here <https://stackoverflow.com/a/63814363>`_).
5. Use the ``Remote-containers: open folder in container`` command and select the ``beobench`` repo in the pop-up window (NOT the ``beobench`` folder inside the repo).
import beobench

0 comments on commit d1b8d74

Please sign in to comment.