jmalkin commented on code in PR #6: URL: https://github.com/apache/datasketches-python/pull/6#discussion_r1322255257
########## requirements.txt: ########## Review Comment: this whole file should not exist ########## .github/workflows/sphinx.yml: ########## @@ -0,0 +1,32 @@ +name: Sphinx + +on: + push: + branches: + - main + workflow_dispatch: + +jobs: + build-documentation: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + - name: Install Python + uses: actions/setup-python@v4 + with: + python-version: '3.x' + - name: Install Datasketches and Sphinx + run: python -m pip install . sphinx==7.2.4 sphinx-rtd-theme Review Comment: with luck we'll be able to remove the pinned version, or else use the fix in the issue about this: https://github.com/sphinx-doc/sphinx/issues/11662#issuecomment-1711017608 ########## docs/source/conf.py: ########## @@ -0,0 +1,36 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +import sys +import os + +# need to fix the paths so that sphinx can find the source code. +sys.path.insert(0, os.path.abspath("../../datasketches")) +sys.path.insert(0, os.path.abspath("../../src")) + + +project = 'datasketches' +copyright = '' Review Comment: 2023 -- we didn't publish these docs before then ########## docs/README.md: ########## @@ -0,0 +1,50 @@ +Follow these steps to build the documentation. +1. Clone the directory in an appropriate location `git clone https://github.com/apache/datasketches-python.git` +2. Switch to the correct branch: `git checkout python-docs`. +3. In project root run `source python-docs-venv/bin/activate` + +If there are problems running the virtual env then you may need to install `virtualenv` +and install the packages manually as below +(nb my environment has `python` aliased to `python3` so just use whichever is appropriate for your installation) +``` +python -m venv python-docs-venv # create a new virtual env named python-docs-venv +source python-docs-venv/bin/activate +python -m pip install sphinx +python -m pip install sphinx-rtd-theme +``` +4. In project root run `python3 -m pip install .` to build the python bindings. +5. Build and open the documentation: +``` +cd python/docs +make html +open build/html/index.html +``` + +## Problems +The `density_sketch` and `tuple_sketch` are not yet included. Review Comment: this seems to be an interaction with sphinx 7.2.5; 7.2.4 should work, and that's why it's pinned in the yaml. we should probably look into including the packages in conf.py as a workaround, only because that seems like it should be mostly harmless. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
