forked from apache/cassandra-java-driver
-
Notifications
You must be signed in to change notification settings - Fork 38
Autogenerate Java docs (II) #38
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| name: "CI Docs" | ||
|
|
||
| on: | ||
| push: | ||
| branches: | ||
| - latest | ||
| tags: | ||
| - '**' | ||
| jobs: | ||
| release: | ||
| name: Build | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - name: Checkout | ||
| uses: actions/checkout@v2 | ||
| with: | ||
| persist-credentials: false | ||
| fetch-depth: 0 | ||
| - name: Set up Python | ||
| uses: actions/setup-python@v1 | ||
| with: | ||
| python-version: 3.7 | ||
| - name: Set up Doxygen | ||
| run: sudo apt-get install doxygen | ||
| - name: Build Sphinx docs | ||
| run: | | ||
| export PATH=$PATH:~/.local/bin | ||
| cd docs | ||
| make multiversion | ||
| - name: Deploy | ||
| run : ./docs/_utils/deploy.sh | ||
| env: | ||
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | ||
| LATEST_VERSION: latest |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -4,8 +4,10 @@ testing/ | |
| .settings | ||
| .classpath | ||
| .project | ||
| doc | ||
| docs | ||
| docs/_build | ||
| docs/_source | ||
| html | ||
| latex | ||
| notes | ||
| .DS_Store | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| Building the Docs | ||
| ================= | ||
|
|
||
| *Note*: The docs build instructions have been tested with Sphinx 2.4.4 and Fedora 32. | ||
|
|
||
| To build and preview the docs locally, you will need to install the following software: | ||
|
|
||
| - `Git <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_ | ||
| - `Python 3.7 <https://www.python.org/downloads/>`_ | ||
| - `pip <https://pip.pypa.io/en/stable/installing/>`_ | ||
| - `doxygen <https://www.tutorialspoint.com/how-to-install-doxygen-on-ubuntu/>`_ | ||
|
|
||
| Run the following command to build the docs. | ||
|
|
||
| .. code:: console | ||
|
|
||
| cd docs | ||
| make preview | ||
|
|
||
| Once the command completes processing, open http://127.0.0.1:5500/ with your preferred browser. | ||
|
|
||
| Building multiple documentation versions | ||
| ======================================== | ||
|
|
||
| Build Sphinx docs for all the versions defined in ``docs/conf.py``. | ||
|
|
||
| The multiverson command does not build doxygen docs. | ||
|
|
||
| .. code:: console | ||
|
|
||
| cd docs | ||
| make multiversion | ||
|
|
||
| Then, open ``docs/_build/dirhtml/<version>/index.html`` with your preferred browser. | ||
|
|
||
| **NOTE:** If you only can see docs generated for the master branch, try to run ``git fetch --tags`` to download the latest tags from remote. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,78 @@ | ||
| # You can set these variables from the command line. | ||
| POETRY = $(HOME)/.poetry/bin/poetry | ||
| SPHINXOPTS = | ||
| SPHINXBUILD = $(POETRY) run sphinx-build | ||
| PAPER = | ||
| BUILDDIR = _build | ||
| SOURCE_DIR = _source | ||
|
|
||
| # Internal variables. | ||
| PAPEROPT_a4 = -D latex_paper_size=a4 | ||
| PAPEROPT_letter = -D latex_paper_size=letter | ||
| ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCE_DIR) | ||
| # the i18n builder cannot share the environment and doctrees with the others | ||
| I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . | ||
|
|
||
| .PHONY: all | ||
| all: dirhtml | ||
|
|
||
| .PHONY: pristine | ||
| pristine: clean | ||
| git clean -dfX | ||
|
|
||
| .PHONY: setup | ||
| setup: | ||
| ./_utils/setup.sh | ||
| cp -Tr source $(SOURCE_DIR) | ||
| cd $(SOURCE_DIR) && find -name README.md -execdir mv '{}' index.md ';' | ||
| .PHONY: clean | ||
| clean: | ||
| rm -rf $(BUILDDIR)/* | ||
| rm -rf $(SOURCE_DIR)/* | ||
|
|
||
| .PHONY: preview | ||
| preview: setup | ||
| cd .. && ./docs/_utils/doxygen.sh | ||
| $(POETRY) run sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500 | ||
|
|
||
| .PHONY: dirhtml | ||
| dirhtml: setup | ||
| $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml | ||
| @echo | ||
| @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." | ||
|
|
||
| .PHONY: singlehtml | ||
| singlehtml: setup | ||
| $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml | ||
| @echo | ||
| @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." | ||
|
|
||
| .PHONY: epub | ||
| epub: setup | ||
| $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub | ||
| @echo | ||
| @echo "Build finished. The epub file is in $(BUILDDIR)/epub." | ||
|
|
||
| .PHONY: epub3 | ||
| epub3: setup | ||
| $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 | ||
| @echo | ||
| @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." | ||
|
|
||
| .PHONY: dummy | ||
| dummy: setup | ||
| $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy | ||
| @echo | ||
| @echo "Build finished. Dummy builder generates no files." | ||
|
|
||
| .PHONY: linkcheck | ||
| linkcheck: setup | ||
| $(SPHINXBUILD) -b linkcheck $(SOURCE_DIR) $(BUILDDIR)/linkcheck | ||
|
|
||
| .PHONY: multiversion | ||
| multiversion: setup | ||
| @mkdir -p $(HOME)/.cache/pypoetry/virtualenvs | ||
| $(POETRY) run ./_utils/multiversion.sh | ||
| @echo | ||
| @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| #!/bin/bash | ||
|
|
||
| # Clone repo | ||
| git clone "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" --branch gh-pages --single-branch gh-pages | ||
| cp -r docs/_build/dirhtml/* gh-pages | ||
| # Redirections | ||
| ./docs/_utils/redirect.sh > gh-pages/index.html | ||
| # Deploy | ||
| cd gh-pages | ||
| touch .nojekyll | ||
| git config --local user.email "[email protected]" | ||
| git config --local user.name "GitHub Action" | ||
| git add . | ||
| git commit -m "Publish docs" || true | ||
| git push origin gh-pages --force |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| #!/bin/bash | ||
|
|
||
| OUTPUT_DIR="docs/_build/dirhtml/api" | ||
| if [[ "$SPHINX_MULTIVERSION_OUTPUTDIR" != "" ]]; then | ||
| OUTPUT_DIR="$SPHINX_MULTIVERSION_OUTPUTDIR/api" | ||
| echo "HTML_OUTPUT = $OUTPUT_DIR" >> doxyfile | ||
| fi | ||
| mkdir -p "$OUTPUT_DIR" | ||
| doxygen doxyfile |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| #! /bin/bash | ||
|
|
||
| cd .. && sphinx-multiversion docs/source docs/_build/dirhtml \ | ||
| --pre-build './docs/_utils/doxygen.sh' \ | ||
| --pre-build "find docs/source -name README.md -execdir mv '{}' index.md ';'" |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| #!/bin/bash | ||
|
|
||
| cat <<- _EOF_ | ||
| <!DOCTYPE html> | ||
| <html> | ||
| <head> | ||
| <title>Redirecting to Driver</title> | ||
| <meta charset="utf-8"> | ||
| <meta http-equiv="refresh" content="0; URL=./${LATEST_VERSION}/index.html"> | ||
| <link rel="canonical" href="./${LATEST_VERSION}/index.html"> | ||
| </head> | ||
| </html> | ||
| _EOF_ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| api: /api/classes.html |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| #! /bin/bash | ||
|
|
||
| if pwd | egrep -q '\s'; then | ||
| echo "Working directory name contains one or more spaces." | ||
| exit 1 | ||
| fi | ||
|
|
||
| which python3 || { echo "Failed to find python3. Try installing Python for your operative system: https://www.python.org/downloads/" && exit 1; } | ||
| which poetry || curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/1.1.3/get-poetry.py | python3 - && source ${HOME}/.poetry/env | ||
| poetry install |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.