Skip to content

Commit 9db5414

Browse files
SplinesSplines
authored
[Python] Init docs (#9)
TL;DR: - Refactor graph python module - Init Sphinx documentation: https://majorminer.readthedocs.io/ * [Py] Implement BFS and DFS for initialization BFS: Breadth-first search DFS: Depth-first search * Refactor undirected Graph and add doc strings. * Init Sphinx ReadTheDocs documentation * Add documentation badge * Add docstrings to graph * Init Chimera graph docs * Add ReadTheDocs configuration to fix doc errors Use Python 3.9 instead of version 3.7 for building. * Add doc strings to embedding graph This partially breaks with some chain logic, so we will need to adjust some functions one abstraction layer above. * Fix get_embedded_nodes * Add overview section to docs including diagrams * Add more docs * Add warning for outdated Readme
1 parent 1fd6a2a commit 9db5414

33 files changed

+1164
-351
lines changed

‎.readthedocs.yaml

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# .readthedocs.yaml
2+
# Read the Docs configuration file
3+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
4+
5+
# Required
6+
version: 2
7+
8+
# Set the version of Python and other tools you might need
9+
# Python 3.9 problem: see https://github.com/readthedocs/readthedocs.org/issues/7554#issuecomment-785114155
10+
build:
11+
os: ubuntu-20.04
12+
tools:
13+
python: "3.9"
14+
15+
# Build documentation in the docs/ directory with Sphinx
16+
sphinx:
17+
configuration: python/docs/source/conf.py
18+
19+
# If using Sphinx, optionally build your docs in additional formats such as PDF
20+
formats:
21+
- pdf
22+
23+
# Optionally declare the Python requirements required to build your docs
24+
# python:
25+
# install:
26+
# - requirements: docs/requirements.txt

‎README.md

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,11 @@
11
# majorminer
2+
[![Documentation Status](https://readthedocs.org/projects/majorminer/badge/?version=latest)](https://majorminer.readthedocs.io/en/latest/?badge=latest)
3+
4+
25
Testing a bunch of graph minor embedding heuristics and related techniques to improve the embedding of QUBOs.
36

47

8+
59
| :warning: | This is a research repo, so APIs and algorithms might change frequently as we are trying out different ideas. Moreover, this means that the code is not production-ready. |
610
|---------------|:------------------------|
711

@@ -12,7 +16,7 @@ Testing a bunch of graph minor embedding heuristics and related techniques to im
1216

1317
<details>
1418
<summary>C++</summary>
15-
19+
1620
# Build C++ library
1721
Note that in order to build, you have to clone the submodules as well. That is,
1822
if you have already cloned this repository, you should run ```git submodule update --init --recursive``` and find the submodules in ```external/```.
@@ -38,6 +42,6 @@ make
3842

3943
<details>
4044
<summary>Python</summary>
41-
45+
4246
All Python-related code and documentation can be found [in the Python folder](python/).
4347
</details>

‎python/README.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# Python evolutionary embedding
22

3+
| :warning: | This Readme is currently outdated. You can find the [documentation here](https://majorminer.readthedocs.io/)|
4+
|---------------|:------------------------|
5+
36
## Usage
47
Execute (from within the python folder):
58

@@ -16,4 +19,4 @@ In order to get **144 unique K4 embeddings on a single chimera cell**, execute (
1619
python -m src.solver.k4_results
1720
```
1821

19-
![144 unique K4 embeddings on a single chimera cell](./images/k4_embedding.svg)
22+
![144 unique K4 embeddings on a single chimera cell](./images/k4_embedding.svg)

‎python/docs/Majorminer Python class diagram.drawio

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
<mxfile host="Electron" modified="2021-11-17T06:44:44.188Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/14.5.1 Chrome/89.0.4389.82 Electron/12.0.1 Safari/537.36" etag="YLhbU3H9Y_1-47_qsndC" version="14.5.1" type="device"><diagram id="C5RBs43oDa-KdzZeNtuy" name="Page-1">7Vtdc9o4FP01zOw+pGPZfPURCEmbpiktabNvjLAFVpEtVhYh5Nf3ypYxRkBMFgJLmMlkrGtZsu85ks+RRclpBU/XAo/9r9wjrGRb3lPJuSzZdg1V4b8KzJJAGX1MAkNBvSSEskCXPhMdtHR0Qj0S5SpKzpmk43zQ5WFIXJmLYSH4NF9twFm+1zEeEiPQdTEzow/Uk34Srdu1LP6J0KGf9oyq+vkCnFbWTxL52OPThZDTLjktwblMjoKnFmEqd2leHj7PHtjtqHp98z36F/9sfrm/+3WRNHa1zSXzRxAklK9u+nk0uPr0q/z7n3Hn6vvUum70by70JdYjZhOdr5+hRwUAQbyYDw3v9y2NpM6AnKVpjaY0YDiEUnPAQ9nVZxCUMaPDEI5duFsiIPBIhKSASEOfkHwMUdenzLvFMz5RzxRJ7I7SUtPngj5Ds5jpNuG0kJpcdjVXo6uuhLAFUUEiqNNJE4XmoVscSV3H5YzhcUT78xsOsBjSsMml5EHaEJ+EHvF0aY58XJCCj+ZcUtcXhEfDqLJBnhbIqeG6JjwgUsygij5rOxoePfRQWp5mREZVHfMXSVwt6wGkB89w3va8ux+AMQ6HkISsP3upP7tgf3Y13x1mAHyIJWmqNEaLtISDhUfNQjFZtyAuMoh7hwNi0BQyLRcoychAriVkNMYuDYe3cZ3Lchb5oZ9UhThcO2AxGXzqeSSMySKxxAmfFEPGnIYyTkWlCX+QsJb1oVKqwA21oIyyMvyp6kK2eAi8wjQmEAGyToki7ApqbRzGL1NrlkdsW2QXiZSDdFv8bAO/js9DRca7SdCHaePUkNwwo/gyYPpwX3hX7LfDu35Rrt/41K98Cab3d21+83g5uCif8V6Pt4FjUQqsxbtWP/D4dgy82wGm6rKG58E7OXrXgO9+gCOrfGDEzRFuQMxoLBh1OtBKMfUC/gEgqZpLAb9XfLi8QAYpHJMUzgoCMNwnrMMjKilX7Yuk7hIxDvWaLqz46nsCtWJO2xPh+jhSMzfo7BGkNz46wQG9P1APPTlXDVS7cuKpxyxo86yzzdudzUNLtsupFrV5zoZhv97moSVb6dSP1+bV1jP1VIVjwWmnWphmx2L56gaWDbh7tXxnW1/hVXJySO5UEW6N91tavpV3/PEsCHcOalFfty89mK7qL4D6GSZ+qw1o0D6OXzP3XAVCwVVzJzakF0VQeV8g1w89UyNzdfWaqFdulwQ0xEIhfo9HkOxTw3dfkCJ06Nk4vYFN0zEJvYb65AalPuNKbjchpPU4spLiFWXpq+sFwZx//xFvSNKhQ1ifT9tZoBkH4ETKlK3ldsTBl5KXIQODMSQF7Jy6243ArgJSEIYlfcx/edwgzjuKuJkwt628MLctJ99E8pD6KnvhU9+2DSVZMBra2ccZc/WvI/iARBE39frZYu7fYjrLlq+oxaxZL5J4hcN0ygUcZu04HCYy1y27mGE9477Dd9t88P5/nCUylykN9N671dge1qIGcm9ew1ymfFeKJUXsqCULWprpa6+ULM5SQ3Zt6V72LVnMlUa99akdQssPVPotHknzK8d5I9T+5Uul8tqNSdar9IvRX7lofwfQL+ayak/yXsjjXZcNRVYi//r73aqZWmGyHY2aMRdOe24898RwetQ9RTx3uli+PeoHXy23Tc981rD/GdZDr5fbprvEntdTUg1m6RMcxntD8uCL4rZpMgUJIL1nNLdH803Xw1duSDU/cYC96AmCXV/l8mTBfM1e0wTf49jQtBJM89tGDszeFOxboqHOuG6Ba/UN95SuxNX82twIoTyZ/0YJCvHPlAxQQUCO1WHIpVI7U59K0gWoVGwKV+RlVB+c8zBWoN8mMlFZcdzDYvRNASxVSqwPVkUhnrjvWtHUr/fAhbeEIeujgUR9BRBok99dgwQUs9+wJa40+yGg0/4D</diagram></mxfile>

‎python/docs/make.bat

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
if "%1" == "" goto help
14+
15+
%SPHINXBUILD% >NUL 2>NUL
16+
if errorlevel 9009 (
17+
echo.
18+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
19+
echo.installed, then set the SPHINXBUILD environment variable to point
20+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
21+
echo.may add the Sphinx directory to PATH.
22+
echo.
23+
echo.If you don't have Sphinx installed, grab it from
24+
echo.https://www.sphinx-doc.org/
25+
exit /b 1
26+
)
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd
36+
37+
pause

‎python/src/graphs/__init__.py renamed to ‎python/docs/source/_static/.gitkeep

File renamed without changes.

‎python/docs/source/_static/embedding_solver_principle.png

216 KB
Loading

‎python/docs/source/_static/python_architecture.png

328 KB
Loading

‎python/docs/source/_templates/.gitkeep

Whitespace-only changes.

‎python/docs/source/api.rst

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
.. _api:
2+
3+
API Reference
4+
=============
5+
6+
7+
Graph Module
8+
------------
9+
10+
.. automodule:: src.graph.undirected_graph
11+
:members:
12+
:undoc-members:
13+
:show-inheritance:
14+
15+
.. automodule:: src.graph.embedding_graph
16+
:members:
17+
:undoc-members:
18+
:show-inheritance:
19+
20+
.. automodule:: src.graph.chimera_graph
21+
:members:
22+
:undoc-members:
23+
:show-inheritance:
24+
25+
26+
More Modules
27+
------------
28+
29+
.. note::
30+
31+
To come soon...

‎python/docs/source/conf.py

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Great tutorial for this setup
2+
# https://samnicholls.net/2016/06/15/how-to-sphinx-readthedocs/#fn-841-5
3+
4+
# In order to build run the following commands:
5+
# luckily ReadTheDocs is doing this automatically for us
6+
7+
# https://stackoverflow.com/a/46349694
8+
# cd docs/
9+
# sphinx-apidoc -o source/ ../src -f
10+
# and after that run:
11+
# ./make.bat html
12+
13+
14+
# Configuration file for the Sphinx documentation builder.
15+
#
16+
# This file only contains a selection of the most common options. For a full
17+
# list see the documentation:
18+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
19+
20+
21+
# -- Path setup --------------------------------------------------------------
22+
23+
# If extensions (or modules to document with autodoc) are in another directory,
24+
# add these directories to sys.path here. If the directory is relative to the
25+
# documentation root, use os.path.abspath to make it absolute, like shown here.
26+
#
27+
import os
28+
import sys
29+
30+
# https://stackoverflow.com/a/44980548
31+
sys.path.insert(0, os.path.abspath('../..'))
32+
33+
34+
# -- Project information -----------------------------------------------------
35+
36+
project = 'majorminer'
37+
copyright = '2021, Dominic Plein, Julien Meier'
38+
author = 'Dominic Plein, Julien Meier'
39+
40+
41+
# -- General configuration ---------------------------------------------------
42+
43+
# Add any Sphinx extension module names here, as strings. They can be
44+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
45+
# ones.
46+
extensions = [
47+
"sphinx.ext.autodoc",
48+
"sphinx.ext.napoleon",
49+
"sphinx.ext.autosummary"
50+
]
51+
52+
# Napoleon setup
53+
napoleon_google_docstring = True # defaults to True
54+
napoleon_use_ivar = True
55+
56+
# Inheritance Diagram
57+
# https://www.sphinx-doc.org/en/master/usage/extensions/inheritance.html
58+
# inheritance_graph_attrs = dict(
59+
# rankdir="TB",
60+
# size='""'
61+
# )
62+
63+
# Add any paths that contain templates here, relative to this directory.
64+
templates_path = ['_templates']
65+
66+
# List of patterns, relative to source directory, that match files and
67+
# directories to ignore when looking for source files.
68+
# This pattern also affects html_static_path and html_extra_path.
69+
exclude_patterns = []
70+
71+
72+
# -- Options for HTML output -------------------------------------------------
73+
74+
# The theme to use for HTML and HTML Help pages. See the documentation for
75+
# a list of builtin themes.
76+
#
77+
html_theme = 'sphinx_rtd_theme'
78+
79+
# Add any paths that contain custom static files (such as style sheets) here,
80+
# relative to this directory. They are copied after the builtin static files,
81+
# so a file named "default.css" will overwrite the builtin "default.css".
82+
html_static_path = ['_static']

‎python/docs/source/index.rst

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
.. majorminer documentation master file
2+
3+
4+
Welcome to the documentation of the majorminer research project realized by two students of the DHBW Karlsruhe. This documentation only includes the API for the Python code, NOT the C++ code.
5+
6+
* :ref:`genindex`
7+
* :ref:`modindex`
8+
9+
10+
Overview
11+
========
12+
13+
.. toctree::
14+
:maxdepth: 2
15+
16+
overview
17+
18+
19+
API Reference
20+
=============
21+
22+
.. toctree::
23+
:maxdepth: 2
24+
25+
api

‎python/docs/source/modules.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
src
2+
===
3+
4+
.. toctree::
5+
:maxdepth: 4
6+
7+
src

‎python/docs/source/overview.rst

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
.. _overview:
2+
3+
Overview
4+
========
5+
6+
Goal
7+
----
8+
9+
.. figure:: /_static/embedding_solver_principle.png
10+
:alt: Principle of the embedding solver
11+
12+
Principle of the embedding solver. Find an embedding for minor H in graph G (in this case: a simple Chimera Graph). Colors indicate different chains (and are not related to the colors in the architecture diagram below).
13+
14+
15+
Python architecture
16+
-------------------
17+
18+
.. figure:: /_static/python_architecture.png
19+
:alt: Python architecture
20+
21+
Simplified overview over the Python architecture. Grey boxes are classes.

‎python/docs/source/src.drawing.rst

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
src.drawing package
2+
===================
3+
4+
Submodules
5+
----------
6+
7+
src.drawing.draw module
8+
-----------------------
9+
10+
.. automodule:: src.drawing.draw
11+
:members:
12+
:undoc-members:
13+
:show-inheritance:
14+
15+
Module contents
16+
---------------
17+
18+
.. automodule:: src.drawing
19+
:members:
20+
:undoc-members:
21+
:show-inheritance:

‎python/docs/source/src.embedding.rst

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
src.embedding package
2+
=====================
3+
4+
Submodules
5+
----------
6+
7+
src.embedding.embedding module
8+
------------------------------
9+
10+
.. automodule:: src.embedding.embedding
11+
:members:
12+
:undoc-members:
13+
:show-inheritance:
14+
15+
src.embedding.graph\_mapping module
16+
-----------------------------------
17+
18+
.. automodule:: src.embedding.graph_mapping
19+
:members:
20+
:undoc-members:
21+
:show-inheritance:
22+
23+
Module contents
24+
---------------
25+
26+
.. automodule:: src.embedding
27+
:members:
28+
:undoc-members:
29+
:show-inheritance:

‎python/docs/source/src.graph.rst

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
src.graph package
2+
=================
3+
4+
Submodules
5+
----------
6+
7+
src.graph.chimera\_graph module
8+
-------------------------------
9+
10+
.. automodule:: src.graph.chimera_graph
11+
:members:
12+
:undoc-members:
13+
:show-inheritance:
14+
15+
src.graph.undirected\_graph module
16+
----------------------------------
17+
18+
.. automodule:: src.graph.undirected_graph
19+
:members:
20+
:undoc-members:
21+
:show-inheritance:
22+
23+
Module contents
24+
---------------
25+
26+
.. automodule:: src.graph
27+
:members:
28+
:undoc-members:
29+
:show-inheritance:

‎python/docs/source/src.rst

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
src package
2+
===========
3+
4+
Subpackages
5+
-----------
6+
7+
.. toctree::
8+
:maxdepth: 4
9+
10+
src.drawing
11+
src.embedding
12+
src.graph
13+
src.solver
14+
15+
Module contents
16+
---------------
17+
18+
.. automodule:: src
19+
:members:
20+
:undoc-members:
21+
:show-inheritance:

0 commit comments

Comments
 (0)