doc and version

doc/Makefile

@@ -48,9 +48,9 @@ html:
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 josch:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) /home/jdilly/Software/Documentation/submitter-doc
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ../../Documentation/submitter-doc
 	@echo
-	@echo "Build finished. The HTML pages are in /home/jdilly/Software/Documentation/submitter-doc."
+	@echo "Build finished. The HTML pages are in ../../Documentation/submitter-doc."
 
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml

doc/_static/css/custom.css

@@ -1,7 +1,41 @@
+:root {
+  --nav-side-width: 300px;  /* default is 300px */
+  /* for 100% width */
+  /*--nav-content-width: 100%;*/
+  /*--local-toc-width: 300px;*/
+  /*--nav-content-width-wide: calc(100% - var(--local-toc-width)); /* 100% here is fullscreen */
+  /*--local-toc-left: calc(100% - var(--local-toc-width)); /* 100% here is w/o sidebar */
+
+  /* for fixed widths */
+  --nav-content-width: 800px;  /* default is 800px */
+  --nav-content-width-wide: var(--nav-content-width);
+  --local-toc-width: calc(100% - var(--nav-content-width-wide));
+  --local-toc-left: calc(var(--nav-content-width-wide) + var(--nav-side-width));
+}
+
+/* main content width */
+.wy-nav-content {
+  max-width: var(--nav-content-width);
+}
+
+/* Sidebar width */
+.wy-nav-side {
+  width: var(--nav-side-width);
+}
+
 .wy-side-nav-search {
   background: rgb(243,244,247);
 }
 
+.wy-side-nav-search > a {
+  color: black;
+}
+
+.wy-side-nav-search> a img.logo {
+  width: 50%;
+}
+
+
 .wy-side-nav-search > div.version {
   color: black;
 }
@@ -182,3 +216,60 @@ em.sig-param span.default_value {
 .rst-content table.field-list th {
   padding: 16px;
 }
+
+
+/* Create local table of contents
+   ------------------------------
+  inspired by https://github.com/readthedocs/sphinx_rtd_theme/pull/919
+  and https://github.com/readthedocs/sphinx_rtd_theme/issues/764
+  see also _templates/layout.html
+ */
+
+#local-table-of-contents {
+  padding-bottom: 20px;
+  /* display: none; */
+}
+
+/* Mask entry of main header (chapter) */
+#local-table-of-contents a[href="#"]{
+  /*display: none;*/
+}
+
+/* indent subsections */
+#local-table-of-contents ul > ul {
+  padding-left: 0px;
+  margin-left: 20px;
+  padding-right: 0;
+  padding-bottom: 5px;
+}
+
+
+#local-table-of-contents-title {
+  margin-bottom: 10px;
+}
+
+/* Show in Sidebar if window width is larger than nav-side + nav-content + toc-width */
+@media screen and (min-width: 1200px) {
+  .wy-nav-content {
+    max-width: var(--nav-content-width-wide);
+  }
+
+  #local-table-of-contents {
+    display: block;
+    position: fixed;
+    margin-left: 15px;
+    overflow-y: auto;
+    height: 95%;
+    top: 45px;
+    left: var(--local-toc-left);
+    width: var(--local-toc-width);
+  }
+
+  #local-table-of-contents-title {
+    display: block;
+    font-size: 16px;
+    width: 100%;
+    padding-top: 10px;
+    padding-bottom: 5px;
+  }
+}

doc/_templates/layout.html

@@ -0,0 +1,12 @@
+{% extends "!layout.html" %}
+{% block document %} 
+  {%- if toc|length > title|length + 75 %}
+  <nav id="local-table-of-contents" role="navigation" aria-labelledby="local-table-of-contents-title">
+    <h4 id="local-table-of-contents-title">On This Page</h4>
+    {{ toc }}
+  </nav>
+  {%- endif %}
+
+  {{ super() }}
+{% endblock %}
+

doc/conf.py

@@ -31,20 +31,10 @@
     sys.path.insert(0, str(TOPLEVEL_DIR))
 
 
-def about_package(init_posixpath: pathlib.Path) -> dict:
-    """
-    Return package information defined with dunders in __init__.py as a dictionary, when
-    provided with a PosixPath to the __init__.py file.
-    """
-    about_text: str = init_posixpath.read_text()
-    return {
-        entry.split(" = ")[0]: entry.split(" = ")[1].strip('"')
-        for entry in about_text.strip().split("\n")
-        if entry.startswith("__")
-    }
 
-
-ABOUT_PYLHC_SUBMITTER = about_package(ABOUT_FILE)
+ABOUT_PYLHC_SUBMITTER: dict = {}
+with ABOUT_FILE.open("r") as f:
+    exec(f.read(), ABOUT_PYLHC_SUBMITTER)
 
 
 # -- General configuration ------------------------------------------------
@@ -66,9 +56,11 @@ def about_package(init_posixpath: pathlib.Path) -> dict:
     "sphinx.ext.githubpages",
     "sphinx.ext.napoleon",
 ]
+autosectionlabel_prefix_document = True
+autosectionlabel_maxdepth = 2
 
 # Add any paths that contain templates here, relative to this directory.
-# templates_path = ['_templates']
+templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
@@ -84,6 +76,11 @@ def about_package(init_posixpath: pathlib.Path) -> dict:
 copyright_ = "2019, pyLHC/OMC-TEAM"
 author = ABOUT_PYLHC_SUBMITTER["__author__"]
 
+# Override link in 'Edit on Github'
+rst_prolog = f"""
+:github_url: {ABOUT_PYLHC_SUBMITTER['__url__']}
+"""
+
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
@@ -98,7 +95,7 @@ def about_package(init_posixpath: pathlib.Path) -> dict:
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

doc/entrypoints/autosix.rst

@@ -1,2 +1,3 @@
 .. automodule:: pylhc_submitter.autosix
     :members:
+    :noindex:

doc/entrypoints/job_submitter.rst

@@ -1,2 +1,3 @@
 .. automodule:: pylhc_submitter.job_submitter
     :members:
+    :noindex:

doc/modules/constants.rst

@@ -1,17 +1,21 @@
 Constants Definitions
-**************************
+*********************
 
 
 .. automodule:: pylhc_submitter.constants.general
     :members:
+    :noindex:
 
 
 .. automodule:: pylhc_submitter.constants.external_paths
     :members:
+    :noindex:
 
 .. automodule:: pylhc_submitter.constants.job_submitter
     :members:
+    :noindex:
 
 .. automodule:: pylhc_submitter.constants.autosix
     :members:
+    :noindex:
 

doc/modules/sixdesk_tools.rst

@@ -3,21 +3,28 @@ Sixdesk Tools
 
 .. automodule:: pylhc_submitter.sixdesk_tools.stages
     :members:
+    :noindex:
 
 .. automodule:: pylhc_submitter.sixdesk_tools.create_workspace
     :members:
+    :noindex:
 
 .. automodule:: pylhc_submitter.sixdesk_tools.submit
     :members:
+    :noindex:
 
 .. automodule:: pylhc_submitter.sixdesk_tools.post_process_da
     :members:
+    :noindex:
 
 .. automodule:: pylhc_submitter.sixdesk_tools.extract_data_from_db
     :members:
+    :noindex:
 
 .. automodule:: pylhc_submitter.sixdesk_tools.utils
     :members:
+    :noindex:
 
 .. automodule:: pylhc_submitter.sixdesk_tools.troubleshooting
     :members:
+    :noindex:

doc/modules/job_submitter_tools.rst → doc/modules/submitter.rst

@@ -1,15 +1,19 @@
-HTCondor Tools
-**************************
+Submitter
+*********
 
 .. automodule:: pylhc_submitter.submitter.htc_utils
     :members:
+    :noindex:
 
 
 .. automodule:: pylhc_submitter.submitter.iotools
     :members:
+    :noindex:
 
 .. automodule:: pylhc_submitter.submitter.mask
     :members:
+    :noindex:
 
 .. automodule:: pylhc_submitter.submitter.runners
     :members:
+    :noindex:

doc/modules/utils.rst

@@ -3,7 +3,9 @@ Utilities
 
 .. automodule:: pylhc_submitter.utils.iotools
     :members:
+    :noindex:
 
 
 .. automodule:: pylhc_submitter.utils.logging_tools
     :members:
+    :noindex:

pylhc_submitter/__init__.py

@@ -10,7 +10,7 @@
 __title__ = "pylhc_submitter"
 __description__ = "pylhc-submitter contains scripts to simplify the creation and submission of jobs to HTCondor at CERN"
 __url__ = "https://github.com/pylhc/submitter"
-__version__ = "1.1.1"
+__version__ = "2.0.0"
 __author__ = "pylhc"
 __author_email__ = "[email protected]"
 __license__ = "MIT"