Skip to content

Commit

Permalink
Updates6 (#22)
Browse files Browse the repository at this point in the history
* New features5 (#21)

* Updating documentation

* You can negate content of single bracket

* Fixing view node attributes

* Moving package build to poetry

* Reformatting with black

* Adding missing devcontainer

* Adding black target

* Removing manually generated documentation

* Updating package build instructions + locale+timezone moved from Dockerfile to devcontainer.json

* Including .vscode configuration

* Exit on first error executing in GNU Makefile

* Minor changes

* Adding task descriptions

* devcontainer configuration cleanup

* Referencing images with URLs

* Setting image URLs to frozen revision

* Allow README.md to be used by pypi and sphinx including all image rendering
  • Loading branch information
mi-parkes authored Oct 13, 2024
1 parent 01563a9 commit 610ba68
Show file tree
Hide file tree
Showing 18 changed files with 163 additions and 341 deletions.
35 changes: 22 additions & 13 deletions .devcontainer/Dockerfile
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
FROM ubuntu:24.04

ARG CACHEBUST=1
ARG PLANTUML_VERSION=1.2024.6
ARG PYTHON_VERSION=3.12

SHELL ["/bin/bash","-c"]

ENV TZ="Europe/Berlin"
ENV LC_ALL en_US.UTF-8
ENV LANG en_US.UTF-8
ENV LANGUAGE en_US.UTF-8

# Update package lists
RUN apt-get update && apt-get upgrade -y

# Install essential packages
RUN DEBIAN_FRONTEND=noninteractive apt install -y \
build-essential libssl-dev zlib1g-dev libbz2-dev libssl-dev \
build-essential \
libssl-dev \
zlib1g-dev \
libbz2-dev \
libssl-dev \
git \
curl \
wget \
Expand All @@ -26,20 +26,29 @@ RUN DEBIAN_FRONTEND=noninteractive apt install -y \
nano \
jq \
openjdk-17-jdk \
python3.12 python3.12-venv python3-pip-whl python3-pip
python${PYTHON_VERSION} \
python${PYTHON_VERSION}-venv \
python3-pip-whl \
python3-pip

RUN apt install -y pipx

RUN mkdir -p /usr/share/plantuml
RUN wget --no-check-certificate \
https://github.com/plantuml/plantuml/releases/download/v1.2024.5/plantuml-mit-1.2024.5.jar \
RUN wget \
https://github.com/plantuml/plantuml/releases/download/v${PLANTUML_VERSION}/plantuml-mit-${PLANTUML_VERSION}.jar \
-O /usr/share/plantuml/plantuml.jar

RUN update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 311
RUN update-alternatives --install /usr/bin/python3 python3 /usr/bin/python${PYTHON_VERSION} 311
RUN ln -s /usr/bin/python3 /usr/bin/python

COPY ./uid_entrypoint /usr/local/bin/
RUN chmod 777 /usr/local/bin/uid_entrypoint

COPY requirements.txt /tmp/requirements.txt
ENV PIPX_HOME=/opt/pipx \
PIPX_BIN_DIR=/usr/local/bin

USER ubuntu
RUN pipx ensurepath
RUN pipx install poetry==1.8.3

USER ubuntu
ENTRYPOINT [ "uid_entrypoint"]
37 changes: 28 additions & 9 deletions .devcontainer/devcontainer.json
Original file line number Diff line number Diff line change
@@ -1,11 +1,30 @@
{
"name": "Python Environment",
// "image": "sphinx-ubuntu-24.04:0.2",
"build": {
"dockerfile": "Dockerfile",
"context": ".."
},
"workspaceFolder": "/workspace",
"runArgs": ["-v", "${localWorkspaceFolder}:/workspace"],
"postCreateCommand": "./uid_entrypoint"
"name": "sphinx-needs-data-explorer-dc",
"build": {
"dockerfile": "Dockerfile",
"context": ".."
},
"runArgs": [
"-v","${localWorkspaceFolder}:/workspace"
],
"workspaceFolder": "/workspace",
"postCreateCommand": "./uid_entrypoint",
"mounts": [
"type=bind,readonly,source=/etc/localtime,target=/etc/localtime"
],
"containerEnv": {
"GITHUB_TOKEN": "${localEnv:GITHUB_TOKEN}",
"GITHUB_USER": "${localEnv:GITHUB_USER}",
"LC_ALL": "en_US.UTF-8",
"LANG": "en_US.UTF-8",
"LANGUAGE": "en_US.UTF-8"
},
"customizations": {
"vscode": {
"extensions": [
"ms-python.python",
"ms-python.debugpy"
]
}
}
}
9 changes: 7 additions & 2 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
.DS_Store
.venv
myvenv
build
doc/build
dist
.vscode

/*.json
/*.zip
/*.bak
docs
sphinx_needs_data_explorer/_static/sphinx_needs_data_explorer_bak*.html
28 changes: 28 additions & 0 deletions .vscode/launch.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
{
"version": "0.3.0",
"configurations": [
{
"name": "Python: Sphinx Module",
"type": "debugpy",
"purpose": [
"debug-in-terminal"
],
"request": "launch",
"module": "sphinx",
"console": "integratedTerminal",
"justMyCode": false,
"stopOnEntry": true,
"args": [
"-b",
"html",
"source",
"build",
"-Ea"
],
"cwd": "${workspaceFolder}/doc",
"env": {
"TEST": "true",
}
},
]
}
15 changes: 15 additions & 0 deletions .vscode/settings.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"esbonio.sphinx.buildDir": "${workspaceFolder}/_build/html",
"esbonio.sphinx.confDir": "${workspaceFolder}/doc/source",
"esbonio.server.showDeprecationWarnings": "false",
"esbonio.server.enabled": true,
"sphinx.quiet": true,
"sphinx.silent": true,
"sphinx.verbosity": 0,
"restructuredtext.syntaxHighlighting.disabled": true,
"plantuml.exportOutDir": "${workspaceFolder}/out",
"plantuml.exportSubFolder": false,
"editor.tabSize": 2,
"editor.insertSpaces": true,
"editor.detectIndentation": false
}
2 changes: 0 additions & 2 deletions MANIFEST.in

This file was deleted.

45 changes: 18 additions & 27 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
.ONESHELL:
SHELL=/bin/bash
.SHELLFLAGS = -e -c

UNAME := $(shell uname 2>/dev/null || echo Windows)

Expand All @@ -24,29 +25,16 @@ helpx:
$(VERBOSE).SILENT:
echo

doc/.venv:
python3 -m venv doc/.venv
source doc/.venv/bin/activate
pip install -r doc/requirements.txt
pip install --upgrade pip

install: doc/.venv
source doc/.venv/bin/activate
install:
rm -rf build dist doc/build
python -m build --sdist --wheel
pip uninstall sphinx-needs-data-explorer -y
pip install dist/sphinx_needs_data_explorer*.whl
poetry install

prep-release: doc/.venv
source doc/.venv/bin/activate
python -m pip install --upgrade twine
prep-release:
rm -rf build dist doc/build
python -m build --sdist
tar -tf dist/*

upload-package:
source doc/.venv/bin/activate
python -m twine upload dist/* --verbose
poetry install
# poetry build
poetry build -f sdist
tar -tf dist/*.tar.gz

installx:
pip uninstall sphinx-needs-data-explorer -y
Expand Down Expand Up @@ -87,19 +75,19 @@ new-install:

echo source $(VENV)/bin/activate

test-package-cur:
$(MAKE) test-package BRANCH=`git branch | awk '$$1=="*"{print $$2}'`

test-package:
$(eval WDIR=/tmp/test)
$(eval BRANCH=updates6)
mkdir -p $(WDIR)
rm -rf $(WDIR)/*
cd $(WDIR)
git clone -b new-features5 --single-branch \
git clone -b $(BRANCH) --single-branch \
https://github.com/mi-parkes/sphinx-needs-data-explorer.git
cd sphinx-needs-data-explorer
# cp $(CURDIR)/pyproject.toml .
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install poetry
# poetry install --only test,docs
poetry install
poetry build
poetry run task doc
Expand All @@ -110,4 +98,7 @@ test-package-show:
$(MAKE) webserver show

show-package:
tar -tvf dist/sphinx_needs_data_explorer-0.9.0.tar.gz
tar -tvf dist/sphinx_needs_data_explorer-*.tar.gz

clean-dc:
docker images | awk '$$1=="<none>"{print "docker rmi "$$3}' | bash
41 changes: 20 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,13 @@

<br>

The `sphinx_needs_data_explorer` is a web application written in HTML, CSS, and JavaScript, provided as a [Sphinx](https://www.sphinx-doc.org/en/master/index.html) extension. It enhances the interactivity of your Sphinx-generated documentation by enabling you to explore <a href="needs.json">Sphinx-Needs-Data</a> generated by the [Sphinx-Needs-Extension](https://www.sphinx-needs.com).
The `sphinx_needs_data_explorer` is a web application written in HTML, CSS, and JavaScript, provided as a [Sphinx](https://www.sphinx-doc.org/en/master/index.html) extension. It enhances the interactivity of your Sphinx-generated documentation by enabling you to explore <a href="[needs.json](https://mi-parkes.github.io/sphinx-needs-data-explorer/needs.json)">Sphinx-Needs-Data</a> generated by the [Sphinx-Needs-Extension](https://www.sphinx-needs.com).

## Goals and Realization

<br>

![](doc/source/images/sphinx_needs_data_explorer.svg)
![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/sphinx_needs_data_explorer.svg)

<br>

Expand All @@ -30,63 +30,63 @@ You can choose **network layout**
- hierarchical right-to-left
- hierarchical with repulsion

![](doc/source/images/network-perspective.jpg)
![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/network-perspective.jpg)

<br>

#### `Table-View`
In Table-View-Perspective you can see sphinx-needs data in table. You can select which columns should
be visible and which hidden.

![](doc/source/images/table-perspective.jpg)
![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/table-perspective.jpg)

<br>

#### `File-View`
In File-View-Perspective, you can see a list of files in which Sphinx-needs data were found.

![](doc/source/images/file-perspective.jpg)
![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/file-perspective.jpg)

<br>

### Powerfull Interactive Data Filtering
You can predefine filtering expressions during documentation generation or interactively while browsing documentation, and apply the data filtering across all three view perspectives.

![](doc/source/images/data-filtering.jpg)
![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/data-filtering.jpg)

You can use attribute lookup table while writing your filters.

![](doc/source/images/scr6.jpg)
![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/scr6.jpg)

<br>

### Exploring In-Neighbours, Out-Neighbours or both

![](doc/source/images/sh2.jpg)
![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/sh2.jpg)

<br>

### Visualizing Constraint Violations in Network Transitions

![](doc/source/images/scr7.jpg)
![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/scr7.jpg)

<br>

### Controlling Neighborhood Depth in Network Visualization

![](doc/source/images/depthview.gif)
![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/depthview.gif)

<br>

### Switching between Perspective Views and Documentation

![](doc/source/images/sh3.jpg)
![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/sh3.jpg)

<br>

### Interaction

![](doc/source/images/sphinx-needs-data-explorer.gif)
![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/sphinx-needs-data-explorer.gif)

<br>

Expand All @@ -100,12 +100,12 @@ Alternatively (Linux)

git clone https://github.com/mi-parkes/sphinx-needs-data-explorer.git
cd sphinx-needs-data-explorer
python3 -m venv .venv
source .venv/bin/activate
pip install -r doc/requirements.txt
python3 -m build --wheel

poetry install
poetry build
poetry run task doc

# you can then install the package in your virtual environment
pip install dist/sphinx_needs_data_explorer*.whl

## Activation
Expand Down Expand Up @@ -136,7 +136,7 @@ or you can include it only if the extension is available in your virtual environ
If your project uses [sphinx_book_theme](https://github.com/executablebooks/sphinx-book-theme),
`sphinx_needs_data_explorer` supports full integration in your documentation by adding `E` header button accesible from any documentation page.

![](doc/source/images/E-header-button-doc.jpg)
![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/E-header-button-doc.jpg)

Otherwise, you can create hyperlink to `sphinx_needs_data_explorer` by adding the following role in your .rst file(s)

Expand Down Expand Up @@ -164,8 +164,7 @@ You can predefine filtering expressions to populate the filter drop-down list:

`sphinx_needs_data_explorer` Help lists all attributes found in your project that can be used for data filtering.

![](doc/source/images/help1.jpg)

![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/help1.jpg)

Visualizing Constraint Violations in Network Transitions:

Expand Down
Loading

0 comments on commit 610ba68

Please sign in to comment.