Metadata-Version: 1.0
Name: girder-tech-journal
Version: 1.0.0a3
Summary: A Girder plugin for a Technical Journal
Home-page: https://github.com/girder/tech_journal
Author: Kitware, Inc.
Author-email: kitware@kitware.com
License: UNKNOWN
Description: Tech Journal Plugin |build-status| |license-badge|
        ==================================================
        
        Assumes a certain folder structure so far for the main page display:
        The top level collection ID value is what should be used in the configuration page
        It will then search for the folders under each, to find all available journal "issues"
        
        From each of those "issues", it will query for a "submission" which is an available folder
        in the "issue".  Eventually, this folder will have metadata for the rest of the information
        that needs to be shown.  A sample structure is found in a graphic diagram below, with the Girder
        type in parenthesis:
        
        .. parsed-literal::
        
           OTJ (collection)
           ├── 2016 Jan-Jun (folder)
           │   ├── Submission 1 (folder)
           │   │   └── Revision 1
           |   |       └── blah.tar
           │   │   └── Revision 2
           |   |       └── blah_v2.tar
           │   └── Submission 2 (folder)
           │   │   └── Revision 1
           │           └── Paper.docx
           └── 2016 Jun-Dec (folder)
               └── Submission 3 (folder)
                   └── Revision 1
                       └── Paper2.docx
        
        Setup Instructions
        ------------------
        
        Install pre-requisite programs
        ++++++++++++++++++++++++++++++
        
        Follow the Girder `System Prerequisites`_ documentation to ensure that all
        necessary programs are available for the pip-installed version of Girder.
        
        **Note:** The Technical Journal plugin requires Node.js 8+. When following the
        documentation to enable the Node.js APT repository, use:
        
        .. code:: bash
        
          curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
        
        **Note:** The Technical Journal plugin requires that MongoDB is at least 3.4+. When following the
        documentation to install MongoDB, replace '3.2' with '3.4'
        
        .. code:: bash
        
          echo "deb http://repo.mongodb.org/apt/debian jessie/mongodb-org/3.4 main" \
            | sudo tee /etc/apt/sources.list.d/mongodb-org-3.4.list
        
        or
        
        .. code:: bash
        
          echo "deb http://repo.mongodb.org/apt/ubuntu xenial/mongodb-org/3.4 multiverse" \
            | sudo tee /etc/apt/sources.list.d/mongodb-org-3.4.list
        
        
        Set up Technical Journal plugin
        +++++++++++++++++++++++++++++++
        The plugin can either be installed directly from pip:
        
        .. code:: bash
        
          pip install girder-tech-journal
        
        Or by cloning this repository
        
        .. code:: bash
        
          git clone https://github.com/girder/tech_journal
          cd tech_journal
          pip install .
        
        In the git repo directory, follow the Installation_ documentation to create a
        virtual environment and install Girder from pypi. Do not install the web client
        libraries yet. The following instructions assume you have entered the virtual
        environment.
        
        Install yarn
        
        .. code:: bash
        
          npm install -g yarn
        
        Install web packages:
        
        .. code:: bash
        
          cd girder-tech-journal-gui
          yarn install
        
        To run the development server:
        
        .. code:: bash
        
          yarn run serve
        
        To build the standalone web application for production:
        
        .. code:: bash
        
          yarn run build
        
        
        If you've cloned the repo and are developing for the plugin, there is a custom command in ``setup.py`` that will
        automate installing yarn packages, building the frontend for production, and copying the dist folder to the proper location.
        To use this, run: ``python setup.py build_ui``.
        
        **WARNING**
        
        If you run ``girder serve`` in development mode, the standalone frontend **will not** be served at ``/tech_journal``.
        This is because it is expected that the frontend will be served on its own (E.g. ``yarn run serve``) in order
        to see the changes being made. If for some reason you need to serve the frontend at ``/tech_journal``, you will need
        to run ``girder serve`` in production mode. However be aware that in this case it is serving the pre-built files,
        and thus no changes will take affect until you rebuild the frontend (E.g. by running ``python setup.py build_ui``).
        
        
        Install girder_worker
        ++++++++++++++++++++++
        
        The submission upload page has the capability to submit a GitHub URL and
        have the Tech Journal download the ``master`` branch of the repository
        to be made available as the download of the submission.  To do this,
        it utilizes the girder_worker_ tool. This is automatically installed when
        installing the Tech Journal plugin.
        
        
        Install RabbitMQ
        ________________
        
        Follow RabbitMQ_ documentation to install.
        
        After installation, ensure that the service is running
        
        .. parsed-literal::
          service --status-all | grep rabbitmq
            [ + ]  rabbitmq-server
        
        
        Install Tech Journal Tasks
        __________________________
        
        The package found in the ``tech_journal_tasks`` directory will also need
        to be installed into the environment prior to starting the ``girder_worker``
        program.
        
        This is accomplished by entering the ``tech_journal_tasks`` directory
        and executing the setup.py file with the ``install`` directive.
        
        .. code:: bash
        
          cd tech_journal_tasks
          pip install .
        
        Start girder_worker
        ___________________
        
        Executing the ``girder_worker`` program will start the task listener. If
        one has accepted the default installation for RabbitMQ, there will be no
        changes necessary to the girder_worker configuration to allow it to connect
        to RabbitMQ.  Start girder_worker with the following command:
        
        .. code:: bash
        
          girder-worker -l info
        
        When viewing the first set of output, ensure that the ``processGitHub`` and
        ``surveySubmission`` tasks are listed under the ``[tasks]`` header:
        
        .. parsed-literal::
        
          snyder@midas-vm:~$ girder-worker -l info
          <....>
        
          [tasks]
            . girder_worker.docker.tasks.docker_run
            . girder_worker.run
            . **tech_journal_tasks.tasks.processGithub**
            . **tech_journal_tasks.tasks.surveySubmission**
        
        Configure the plugin
        ++++++++++++++++++++
        
        Open a new terminal and activate the virtual environment.
        
        .. code:: bash
        
          cd tech_journal
          . ~/girder_env/bin/activate
        
        Build the Girder web client and start the server:
        
        .. code:: bash
        
          girder build
          girder serve
        
        **Note:** although ordinarily Girder would want to rebuild the newly activated
        plugin, you do not need to do that now, since we are building this plugin in a
        "standalone" mode, outside the control of Girder's build system
        
        Create Admin User
        __________________
        
        Open http://localhost:8080/ in your web browser, and you should see the
        Girder welcome page.
        
        The first user to be created in the system is automatically given admin
        permission over the instance, so the first thing you should do after starting
        your instance for the first time is to register a user. After that succeeds,
        you should see a link appear in the navigation bar that says Admin console.
        
        Generate Folder Structure
        _________________________
        
        First, generate a "Collection" to represent the total information of the OTJ.
        This can be accomplished by clicking on ``Collections`` in the left menu and
        then clicking on the ``Create Collection`` button. Enter a name and a
        description, then click ``Create``.
        
        This creation of the collection can also be done by utilizing the
        ``plugins/admin/journal`` page of the OTJ.
        
        **Note**  The description of the collection must contain the string
        ``__journal__`` to be picked up by certain OTJ pages.
        
        The "Unique ID" of this folder, which can be found by clicking on the blue
        button with  an ``i`` on it, will be used later to configure the Tech Journal
        plugin.
        
        Then, generate a folder within that collection to be the first "Issue" that will
        be submitted to. This is accomplished by clicking on the ``Collection Actions``
        menu and selecting ``Create folder here``.  The ``Collection Actions`` button
        can be found to the right of the blue button from above. Enter a name and
        description for the first folder and then click "Create" again.
        
        
        Enable the Technical Journal plugin
        ___________________________________
        
        
        To enable the plugin, head to the ``Admin Console`` and click on the
        ``Plugins`` link.
        
        A list of the current plugins will be shown, scroll down to the
        ``Technical Journal Plugin`` and enable it by switching the ``OFF`` slider
        to the on position.
        
        Click on the ``Configure Plugin`` icon, which looks like a small gear.
        
        This will show the 5 fields that are used to configure a Midas instance of
        the Technical Journal.  Only the ``Default Journal`` entry will need to be
        filled out at this point.  Enter the ``Unique ID`` of the collection that was
        generated above and click ``Save Configuration``.
        
        Once that has been saved, the plugin should be configured and ready to be used.
        Visit the entry point of the plugin by visiting::
        
           http://<webroot>/tech_journal
        
        Or something like this for a localhost instance::
        
          http://localhost:8080/tech_journal
        
        **WARNING**
        
        Some of the links, ``Journal`` and ``Help``, in the menu bar do not point to
        valid locations within the plugin yet.  The ``Home`` and ``New Submission``
        links will take you to the correct pages.
        
        
        Releasing
        _________________________
        
        To update the PyPI release:
        
        First increment the version is setup.py. Then run:
        
        .. code:: bash
        
          cd girder-tech-journal-gui;
          yarn run build;
          cd ..;
          python setup.py sdist;
          tox -e release
        
        
        .. |build-status| image:: https://circleci.com/gh/girder/tech_journal.png?style=shield
            :target: https://circleci.com/gh/girder/tech_journal
            :alt: Build Status
        
        .. |license-badge| image:: https://img.shields.io/github/license/girder/tech_journal.svg
            :target: https://raw.githubusercontent.com/girder/tech_journal/master/LICENSE
            :alt: License
        
        .. _`System Prerequisites`: https://girder.readthedocs.io/en/stable/prerequisites.html
        .. _`Installation`: https://girder.readthedocs.io/en/stable/installation.html
        .. _Girder_Worker: https://github.com/girder/girder_worker
        .. _RabbitMQ: https://www.rabbitmq.com/download.html
        
Platform: UNKNOWN
