Document how to update documentation

[musale]

Description

I have bootstrapped the steps needed for local installation, building and editing of the documentation for this project.

Reference to official issue

This addresses the issue #41

Motivation and Context

This change enables developers to be able to edit the documentation locally. Since docker is the official development configuration, I used it to create the application and link it to the current development.

How Has This Been Tested?

Locally, when you run

$ docker-compose -f local.yml up

the documentation application will be running on (http://localhost:8002/)[http://localhost:8002/]

CLA

• I have signed the CLA; if other committers are in the commit history, they have signed the CLA as well

[reubano]

Hi @musale the PR looks good! I'll follow your instructions and see if I can successfully update the docs.

[musale]

@reubano great! Kindly let me know of any changes that would improve the experience

[lamby]

@musale This is great, thank you.

[reubano]

I got as far as this....

(alcf) reubano@tokpro ⚡ docker-compose -f local.yml build
postgres uses an image, skipping
Building compile_docs
(alcf) reubano@tokpro ⚡ docker-compose -f local.yml up
Creating network "alcfprod_default" with the default driver
ERROR: failed to update bridge store for object type *bridge.networkConfiguration: open /mnt/sda1/var/lib/docker/network/files/local-kv.db: no such file or directory

[reubano]

Ok, getting further...

(alcf) reubano@tokpro ⚡ docker-machine rm default
(alcf) reubano@tokpro ⚡ docker-machine create --driver virtualbox default
(alcf) reubano@tokpro ⚡ docker-compose -f local.yml up
Creating network "alcfprod_default" with the default driver
Creating volume "alcfprod_postgres_data_dev" with default driver
Pulling postgres (postgres:9.6)...
9.6: Pulling from library/postgres
ad74af05f5a2: Pulling fs layer
...

[musale]

hi @reubano, did you manage to get your docker up and running?

[reubano]

not quite yet...

(alcf) reubano@tokpro ⚡ docker-compose -f local.yml up
Starting alcfprod_postgres_1 ...
Starting alcfprod_compile_docs_1 ...
Starting alcfprod_postgres_1
Starting alcfprod_prediction_1 ...
Starting alcfprod_compile_docs_1
Starting alcfprod_compile_docs_1 ... done
Starting alcfprod_documentation_1 ...
Starting alcfprod_prediction_1 ... done
Starting alcfprod_interface_1 ...
Starting alcfprod_interface_1 ... done
Attaching to alcfprod_postgres_1, alcfprod_compile_docs_1, alcfprod_prediction_1, alcfprod_documentation_1, alcfprod_interface_1
postgres_1       | LOG:  database system was shut down at 2017-08-22 07:58:20 UTC
compile_docs_1   | make: Entering directory '/app/docs'
compile_docs_1   | make: Leaving directory '/app/docs'
postgres_1       | LOG:  MultiXact member wraparound protections are now enabled
compile_docs_1   | make: *** No rule to make target 'html'.  Stop.
postgres_1       | LOG:  database system is ready to accept connections
alcfprod_compile_docs_1 exited with code 2
interface_1      | Postgres is up - continuing...
interface_1      | python: can't open file 'manage.py': [Errno 2] No such file or directory
interface_1      | python: can't open file 'manage.py': [Errno 2] No such file or directory
alcfprod_interface_1 exited with code 2
prediction_1     |  * Serving Flask app "src/factory.py"
prediction_1     |  * Forcing debug mode on
compile_docs_1   | make: *** /app/docs: No such file or directory.  Stop.
compile_docs_1   | make: *** /app/docs: No such file or directory.  Stop.
compile_docs_1   | make: *** No rule to make target 'html'.  Stop.

trying the master branch now to see if I get the same errors...

[lamby]

@reubano Can't reproduce your failure. I wonder what's up...

[reubano]

@lamby I suspect I have deeper issues related to my docker setup. So I wouldn't worry too much about the above error.

[reubano]

@musale I guess this is good to go now. Can you rebase to master and squash to one commit? Thanks!

[lamby]

@musale I guess this is good to go now. Can you rebase to master and squash to one commit? Thanks!

Hey @musale, how are you getting on? :)

[WGierke]

I guess this happened during merging at some point? :)

[musale]

Yes @WGierke I am having a difficult time making this work 😭

[lamby]

Just as a drive-by comment for next time, my experience is that whenever your commit message is a bulleted list of 'n' things that it changes, it should have been 'n' commits to begin with — so much easier to review for all involved!

[musale]

Hey @musale, how are you getting on? :)

Hi @reubano and @lamby! I've been offline the past few days. I have come to a host of additional commits so I had some challenges rebasing and squashing. I have failing tests for both documentation and prediction. Can you check if it's good to go on your end?

[reubano]

@musale... hmmm, one option (if it is feasible) is to save your updates to a location outside of the git repo. Then do a git fetch master and git reset --hard master. That will get you a clean slate to start from. Then reapply the previous changes. Be careful though git reset --hard will erase all of your work, so make sure those changes are saved elsewhere.

[reubano]

Then once it's looking good, you can git push -f back to your PR branch.

[musale]

@reubano let me try this. I will update as soon as I'm done

[musale]

Hi @reubano, I followed your recommendations and finally managed to fix this PR. Kindly check on your end 😀