Added sphinx_scylladb_theme

[dgarcia360]

Added sphinx_scylladb_theme with minimum changes.

Instructions to preview the docs:

1. Create a virtualenv.
   pip install --user virtualenv
python3 -m virtualenv venv
source venv/bin/activate
2. Build and preview docs
   cd docs
make preview

Fixed on 31/05 : Note: The project does not come with a make preview command (livereload).

[tzach]

Got an error at the first command

Create a virtualenv.
python3 -m virtualenv

$ python3 -m virtualenv
/home/tzach/project/scylla-machine-image/.venv/bin/python3: No module named virtualenv

[tzach]

Had issue with build

python setup.py build_ext --inplace --force
Did not find 'Python.h' in ['/usr/include/python3.7m'].
Bypassing Cython setup requirement
running build_ext
Failed to cythonize one or more modules. These will not be compiled as extensions (optional).
building 'cassandra.cmurmur3' extension
gcc -pthread -Wno-unused-result -Wsign-compare -DDYNAMIC_ANNOTATIONS_ENABLED=1 -DNDEBUG -O2 -g -pipe -Wall -Werror=format-security -Wp,-D_FORTIFY_SOURCE=2 -Wp,-D_GLIBCXX_ASSERTIONS -fexceptions -fstack-protector-strong -grecord-gcc-switches -m64 -mtune=generic -fasynchronous-unwind-tables -fstack-clash-protection -fcf-protection -D_GNU_SOURCE -fPIC -fwrapv -fPIC -I/usr/include/python3.7m -c cassandra/cmurmur3.c -o build/temp.linux-x86_64-3.7/cassandra/cmurmur3.o
cassandra/cmurmur3.c:14:10: fatal error: Python.h: No such file or directory
   14 | #include <Python.h>
      |          ^~~~~~~~~~
compilation terminated.

My understanding is not related to the docs.

[tzach]

@dgarcia360 the doc do use the Scylla Theme, but the links from the index file:
file:///home/tzach/project/dgarcia360-python-driver/docs/_build/dirhtml/index.html

does not works.
I suspect a server need to be used. Is it the case?

[dgarcia360]

I suspect a server need to be used. Is it the case?

@tzach Correct, a server is needed to preview the PR in local. I have added in the last commit the preview script already available in other docs under ./docs/_utils/preview.sh and updated the installation instructions.

My understanding is not related to the docs.

@tzach This instruction was listed as necessary in the original script from datastax used to build the docs. I assumed it is indispensable since some parts of the docs are autogenerated and imported from the python-driver.

To be able to set up the python-driver on ubuntu, the installation script requested me to install some system dependencies manually:

sudo apt-get install libev4 libev-dev
sudo apt-get install build-essential python-dev

I'll do some extra tests and remove the line if it's not needed. The latest commit wraps the dependencies set up under ./docs/_utils/setup.sh.

[dgarcia360]

@tzach @lauranovich Added GitHub Actions automation in the latest commit. The script publishes automatically to the gh-pages branch the docs every time the master branch is updated. You can see a preview of docs build with the script here: https://dgarcia360.github.io/python-driver/

After merging the commit, the GitHub Actions scripts should run automatically. I'm sending you via Slack some extra steps you might need to apply in order to enable the GitHub Pages deployment.

[tzach]

Thanks @dgarcia360 very nice!
Note Travis CI still fail, so we can not merge this PR yet.

[tzach]

@dgarcia360 the HP of the driver, looks very different than the internal pages (which look like Scylla Docs)
https://docs.google.com/document/d/1rHQeb1VInIDlf3-qytEJh9jEF-1ws2CiwxlciKXCwps/edit

Why is that?
If its the RST itself, we can fix it in a followup PR

[tzach]

@dgarcia360 I prefer to to share the docs publicly yet, can you please remove it (for now)
and add a local preview option?

[fruch]

@tzach it's o.k. that Travis fails, I've enabled it just last week, and we didn't merge yet the needed change to make it work, (this tarvis configuration comes from the upstream, and we know it's broken)

@dgarcia360 can you send me the instruction for the github actions configuration ?
cause seems like we need to add a github token for it to work.

[fruch]

@tzach I think we should first merge #1 and #2, and only then merge this.

[fruch]

LGTM
a nitpick, about duplicate file, and duplicate comment.

I'm not happy with @dgarcia360 doing the fun stuff of uploding to gh-pages :)

[fruch]

@tzach I think we should first merge #1 and #2, and only then merge this.

Looking at them again, they are just changing the README.rst, and I've merged them anyhow now.

[dgarcia360]

@dgarcia360 can you send me the instruction for the github actions configuration ?
cause seems like we need to add a github token for it to work.

@fruch

• GITHUB_TOKEN: This variable will automatically added after the PR is merged (no action needed). More info https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token#about-the-github_token-secret

• GITHUB_REPOSITORY: This variable is also a constant already available, no action needed.

I have shared with @lauranovich and @tzach some additional instructions on how to set up a custom domain and how to enable GitHub pages once the PR is merged, I can forward them to you via ScyllaDB Slack.

[tzach]

have shared with @lauranovich and @tzach some additional instructions on how to set up a custom domain and how to enable GitHub pages once the PR is merged, I can forward them to you via ScyllaDB Slack.

Better to have this in the project Wiki

[dgarcia360]

@tzach I agree, the wiki looks like the right place to add this info. However, I cannot see/add content to the project wiki (unsure if it's the GitHub wiki or an internal wiki). In the first case, the GitHub wiki for this project may be disabled or requires to have contributor rights to access the tab. Please, let me know if you could add the information shared on Slack to the Wiki or if you prefer to activate the wiki / grant me access to post it.

[fruch]

@tzach I agree, the wiki looks like the right place to add this info. However, I cannot see/add content to the project wiki (unsure if it's the GitHub wiki or an internal wiki). In the first case, the GitHub wiki for this project may be disabled or requires to have contributor rights to access the tab. Please, let me know if you could add the information shared on Slack to the Wiki or if you prefer to activate the wiki / grant me access to post it.

I've enabled the wiki module, see if you can edit/add things there
also the gh-pages is enabled for this repo

[tzach]

@fruch if you are OK with this PR, lets merge it and open new issues for leftovers
It becoming hard to handle

[dgarcia360]

@fruch

I've enabled the wiki module, see if you can edit/add things there

Thanks! I have just posted my notes on this new page Documentation Notes.

@tzach @fruch

@dgarcia360 I prefer to to share the docs publicly yet, can you please remove it (for now)
and add a local preview option?

GitHub Pages deployment can be disabled although the PR is merged. Please, see Disabling Github Pages