From 60fe12414a8c1f137d2750a384e853f6882aa2d4 Mon Sep 17 00:00:00 2001 From: Kali Kaneko Date: Mon, 2 Oct 2017 23:41:01 +0200 Subject: [docs] move js docs to its own section --- README.rst | 107 ++----------------------------------------------- docs/changelog.rst | 5 +-- docs/hacking/uidev.rst | 106 +++++++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 111 insertions(+), 107 deletions(-) diff --git a/README.rst b/README.rst index b8c109f7..4b456203 100644 --- a/README.rst +++ b/README.rst @@ -90,6 +90,8 @@ installed. You can run ui tests like this:: cd ui && make test +More info abou testing can be found in the ``docs/hacking/testing`` document. + Hacking ----------------------------------------------------------- @@ -116,110 +118,9 @@ you can run:: inside your virtualenv, and it will install any new version of your dependencies that is found in pypi. +Checkout the ``docs/hacking`` sections for more advanced instructions to get +you started. -Run headless backend in development mode -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -Prerequisites:: - - sudo apt install build-essential python-dev python-virtualenv \ - libsqlcipher-dev libssl-dev libffi-dev - -Install and activate a virtualenv:: - - cd bitmask-dev - virtualenv venv - source venv/bin/activate - -(Refer to the `virtualenv documentation` if you're not using bash/zsh/dash). - -All the subsequent commands assume that you have activated the virtualenv. - -Install all the python dependencies:: - - make dev-backend - -Run application:: - - bitmaskd - -.. _`virtualenv documentation`: https://virtualenv.pypa.io/en/stable/userguide/#activate-script - -Run user interface frontend -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -If you want to run the Bitmask user interface, you additionally need the -following: - -Prerequisites:: - - sudo apt install python-pyqt5 python-pyqt5.qtwebkit - -Install python dependencies:: - - make dev-all - -Note: even though the UI is in javascript, Qt is used to create a webview -window. - -Run user interface:: - - bitmask - -The command `bitmask` should be in your path if you have activated the virtual -environment. - -Install Bitmask user interface in development mode -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -The above instructions will install a python package that contains a pre- -bundled version of the javascript UI. - -If you want to modify the javascript UI, then you need to be able to update the -javascript bundle whenever a javascript or CSS source file changes. To support -this, we build a python package of the javascript UI and install it in -"development mode" so that changes to the contents of the package are reflected -in bitmaskd immediately. - -Prerequisites:: - - sudo apt install nodejs npm nodejs-legacy - -Next, run ``dev-install``:: - - cd ui - make dev-install - -Now you should be able to run the user interface with debugging tools:: - - bitmaskd - cd ui - npm run ui - -This command is the same as running:: - - chromium-browser "http://localhost:7070/#$(cat ~/.config/leap/authtoken)" - -Firefox does not work as well, because the UI is only tested with webkit-based -browsers. - -Chromium is not the most ideal, however, because it uses a newer webkit than is -available in Qt. Instead, try qupzilla:: - - sudo apt install qupzilla - bitmaskd - qupzilla -ow "http://localhost:7070/#$(cat ~/.config/leap/authtoken)" - -If you make a change to any of the CSS or JS source files, you need to rebuild -the javascript bundle. You can do this continually as files change like so:: - - cd ui - node run watch - -The new javascript bundle will be used when you refresh the page so long as -``make dev-install`` was previously run. - -For more information, see ``ui/README.md``. License =========================================================== diff --git a/docs/changelog.rst b/docs/changelog.rst index dd83f21e..0212b0d1 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -1,9 +1,8 @@ Changelog ===================== -0.10.0 - la rosa de foc - `master`_ ------------------------------------- -.. note:: This version is not yet released and is under active development. +0.10.0 - la rosa de foc +----------------------- Features ~~~~~~~~ diff --git a/docs/hacking/uidev.rst b/docs/hacking/uidev.rst index 4ada825e..968fa010 100644 --- a/docs/hacking/uidev.rst +++ b/docs/hacking/uidev.rst @@ -3,4 +3,108 @@ Bitmask's Javascript User Interface ==================================== -(stuff goes here). +Some notes specific to development of the javascript ui interface. For more detail, see ``ui/README.md``. + +Run headless backend in development mode +---------------------------------------- + +Prerequisites:: + +.. note: move this snippet to a common include! + + sudo apt install build-essential python-dev python-virtualenv \ + libsqlcipher-dev libssl-dev libffi-dev + +Install and activate a virtualenv:: + + cd bitmask-dev + virtualenv venv + source venv/bin/activate + +(Refer to the `virtualenv documentation` if you're not using bash/zsh/dash). + +All the subsequent commands assume that you have activated the virtualenv. + +Install all the python dependencies:: + + make dev-backend + +Run application:: + + bitmaskd + +.. _`virtualenv documentation`: https://virtualenv.pypa.io/en/stable/userguide/#activate-script + +Run user interface frontend +--------------------------- + +If you want to run the Bitmask user interface, you additionally need the +following: + +Prerequisites:: + + sudo apt install python-pyqt5 python-pyqt5.qtwebkit + +Install python dependencies:: + + make dev-all + +Note: even though the UI is in javascript, Qt is used to create a webview +window. + +Run user interface:: + + bitmask + +The command `bitmask` should be in your path if you have activated the virtual +environment. + +Install Bitmask user interface in development mode +-------------------------------------------------- + +The above instructions will install a python package that contains a pre- +bundled version of the javascript UI. + +If you want to modify the javascript UI, then you need to be able to update the +javascript bundle whenever a javascript or CSS source file changes. To support +this, we build a python package of the javascript UI and install it in +"development mode" so that changes to the contents of the package are reflected +in bitmaskd immediately. + +Prerequisites:: + + sudo apt install nodejs npm nodejs-legacy + +Next, run ``dev-install``:: + + cd ui + make dev-install + +Now you should be able to run the user interface with debugging tools:: + + bitmaskd + cd ui + npm run ui + +This command is the same as running:: + + chromium-browser "http://localhost:7070/#$(cat ~/.config/leap/authtoken)" + +Firefox does not work as well, because the UI is only tested with webkit-based +browsers. + +Chromium is not the most ideal, however, because it uses a newer webkit than is +available in Qt. Instead, try qupzilla:: + + sudo apt install qupzilla + bitmaskd + qupzilla -ow "http://localhost:7070/#$(cat ~/.config/leap/authtoken)" + +If you make a change to any of the CSS or JS source files, you need to rebuild +the javascript bundle. You can do this continually as files change like so:: + + cd ui + node run watch + +The new javascript bundle will be used when you refresh the page so long as +``make dev-install`` was previously run. -- cgit v1.2.3