docs: change theme to Furo, to enable dark mode

CMakeLists.txt

@@ -403,7 +403,7 @@ endif()
 add_executable(test_disulf EXCLUDE_FROM_ALL tests/disulf.cpp)
 target_link_libraries(test_disulf PRIVATE gemmi_cpp)
 
-# auth_label requires <experimental/filesystem> and -lstdc++fs
+# auth_label requires C++17 for <filesystem>
 add_executable(auth_label EXCLUDE_FROM_ALL examples/auth_label.cpp)
 target_link_libraries(auth_label PRIVATE gemmi_cpp)
 

docs/_static/custom.css

@@ -0,0 +1,69 @@
+
+/* Use different background color for C++ and Python code blocks. */
+.highlight-pycon .highlight, .highlight-python .highlight {
+ background: #fcfcce;
+}
+.highlight-cpp .highlight {
+ background: #e2ffef;
+}
+/* adjust highlighted lines */
+.highlight-python .highlight .hll {
+ background: #fff0aa; /* original #ffffcc */
+}
+.highlight-cpp .highlight .cpf { /* e.g. <cassert> */
+ color: #108080 /* original #408090 is too similar to our background */
+}
+.highlight-cpp .highlight .s { /* "strings" */
+ color: #107090 /* original #4070a0 */
+}
+.highlight-cpp .highlight .mi,
+.highlight-cpp .highlight .mf { /* integers and floats */
+ color: #008040 /* original #208050 */
+}
+
+/* In dark mode, instead of changing bg color we add Python logo */
+@media (prefers-color-scheme: dark) {
+ body:not([data-theme="light"]) .highlight-pycon,
+ body:not([data-theme="light"]) .highlight-python,
+ body:not([data-theme="light"]) .highlight-cpp {
+  position: relative;
+ }
+ body:not([data-theme="light"]) .highlight-pycon::after,
+ body:not([data-theme="light"]) .highlight-python::after,
+ body:not([data-theme="light"]) .highlight-cpp::after {
+  content: "";
+  background-size: contain;
+  background-repeat: no-repeat;
+  width: 24px;
+  height: 24px;
+  position: absolute;
+  top: 5px; /* from the top edge */
+  right: 5px; /* from the right edge */
+  pointer-events: none; /* no interactions */
+ }
+ body:not([data-theme="light"]) .highlight-pycon::after,
+ body:not([data-theme="light"]) .highlight-python::after {
+  background-image: url("../_static/py.png");
+  opacity: 0.5;
+ }
+ body:not([data-theme="light"]) .highlight-cpp::after {
+  background-image: url("../_static/cpp.png");
+  opacity: 0.6;
+ }
+}
+
+/* roles used in mol.rst */
+.orange-fg { color:#d50; }
+.blue-bg { background-color:#ace; }
+/* roles used in cif.rst */
+.orange-bg { background-color:#fc8; }
+.yellow-bg { background-color:#ffa; }
+.cyan-bg { background-color:#aff; }
+.greenish-bg { background-color:#bd8; }
+@media (prefers-color-scheme: dark) {
+ body:not([data-theme="light"]) .blue-bg { background-color:#138; }
+ body:not([data-theme="light"]) .orange-bg { background-color:#950; }
+ body:not([data-theme="light"]) .yellow-bg { background-color:#660; }
+ body:not([data-theme="light"]) .cyan-bg { background-color:#055; }
+ body:not([data-theme="light"]) .greenish-bg { background-color:#350; }
+}

docs/_templates/page.html

@@ -0,0 +1,10 @@
+{% extends "!page.html" %}
+
+{% block footer %}
+{# Copyright and (c) are redundant, leave only (c) #}
+{{ super() | replace('Copyright ', '')
+           | replace('Made with', 'Built with')
+           | replace('<a class="muted-link" href="https://pradyunsg.me">@pradyunsg</a>\'s',
+                     'customized theme')
+}}
+{% endblock %}

docs/cif.rst

@@ -1666,20 +1666,20 @@ some columns seem to be completely redundant. Are they?
 
 .. raw:: html
 
-    <table style="font-size:11px; border-spacing:5px 0; margin-top:60px; width:100%; border-collapse:separate;">
+    <table style="font-size:11px; border-spacing:5px 0; margin-top:60px; width:100%; border-collapse:separate; overflow-wrap: normal;">
     <colgroup>
     <col span="3">
-    <col style="background-color:#fc8">
+    <col class="orange-bg">
     <col>
-    <col style="background-color:#ffa">
-    <col style="background-color:#aff">
+    <col class="yellow-bg">
+    <col class="cyan-bg">
     <col>
-    <col style="background-color:#bd8">
+    <col class="greenish-bg">
     <col span="12">
-    <col style="background-color:#bd8">
-    <col style="background-color:#ffa">
-    <col style="background-color:#aff">
-    <col style="background-color:#fc8">
+    <col class="greenish-bg">
+    <col class="yellow-bg">
+    <col class="cyan-bg">
+    <col class="orange-bg">
     <col>
     </colgroup>
     <tr style="font-size:10px;">
@@ -1811,7 +1811,7 @@ We compile it, run it, and come back after an hour:
 
 .. code-block:: none
 
-    $ g++-6 -O2 -Iinclude examples/auth_label.cpp -lstdc++fs -lz
+    $ g++ -O2 -Iinclude examples/auth_label.cpp src/gz.cpp -lz
     $ ./a.out pdb_copy/mmCIF
     3D3W: atom_id  O1 -> OD
     1TNI: atom_id  HN2 -> HN3
@@ -1844,8 +1844,10 @@ We compile it, run it, and come back after an hour:
     1AGG: atom_id  H3 -> H
     1AGG: atom_id  H3 -> H
 
-So, as of April 2017, only a single author's residue name was changed,
-and atom names were changed in 7 PDB entries.
+Update: the result above is from 2017.
+In the meantime, the PDB removed the differences.
+Tags auth_atom_id and auth_comp_id are now completely redundant
+(they always have been, except for mistakes).
 
 Amino acid frequency
 --------------------

docs/conf.py

@@ -2,13 +2,12 @@
 
 # -- General configuration ------------------------------------------------
 
+# while we use Sphinx 8+, old version suffices to run doctests
 needs_sphinx = '5.3.0'
 
 extensions = ['sphinx.ext.doctest', 'sphinx.ext.githubpages']
 
-#templates_path = ['_templates']
-
-source_suffix = '.rst'
+templates_path = ['_templates']
 
 master_doc = 'index'
 
@@ -25,14 +24,24 @@
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 pygments_style = 'sphinx'
 todo_include_todos = False
-highlight_language = 'c++'
+highlight_language = 'cpp'
 default_role = 'literal'
 
 
 # -- Options for HTML output ----------------------------------------------
 
-html_theme = 'sphinx_rtd_theme'
-html_static_path = ['custom.css']
+html_theme = 'furo'
+html_theme_options = {
+    "source_repository": "https://github.com/project-gemmi/gemmi/",
+    "source_branch": "master",
+    "source_directory": "docs/",
+}
+html_static_path = ['_static']
+html_css_files = ['custom.css']
+
+# Edit link can be also used to see the source
+html_show_sourcelink = False
+html_copy_source = False
 
 # -- Options for LaTeX output ---------------------------------------------
 
@@ -91,5 +100,3 @@
 gemmi.set_leak_warnings(False)
 '''
 
-def setup(app):
-    app.add_css_file('custom.css')

docs/mol.rst

@@ -1068,26 +1068,26 @@ So once again, now in a color-coded version:
 
 .. raw:: html
 
- <div class="highlight"><pre style="color:#444">
- ATOM   <b>1032</b> O <span style="color:#d50">OE2 <span style="background-color:#ace">.</span> GLU B</span> 2  <span style="color:#d50">72</span>  <span style="background-color:#ace">?</span> -9.804  19.834  -55.805 1.00 25.54 ? <span style="background-color:#ace">77   GLU H OE2</span> 1
- ATOM   <b>1033</b> N <span style="color:#d50">N   <span style="background-color:#ace">A</span> ARG B</span> 2  <span style="color:#d50">73</span>  <span style="background-color:#ace">A</span> -4.657  24.646  -55.236 0.11 20.46 ? <span style="background-color:#ace">77   ARG H N  </span> 1
- ATOM   <b>1034</b> N <span style="color:#d50">N   <span style="background-color:#ace">B</span> ARG B</span> 2  <span style="color:#d50">73</span>  <span style="background-color:#ace">A</span> -4.641  24.646  -55.195 0.82 22.07 ? <span style="background-color:#ace">77   ARG H N  </span> 1
+ <div class="highlight raw"><pre>
+ ATOM   <b>1032</b> O <span class="orange-fg">OE2 <span class="blue-bg">.</span> GLU B</span> 2  <span class="orange-fg">72</span>  <span class="blue-bg">?</span> -9.804  19.834  -55.805 1.00 25.54 ? <span class="blue-bg">77   GLU H OE2</span> 1
+ ATOM   <b>1033</b> N <span class="orange-fg">N   <span class="blue-bg">A</span> ARG B</span> 2  <span class="orange-fg">73</span>  <span class="blue-bg">A</span> -4.657  24.646  -55.236 0.11 20.46 ? <span class="blue-bg">77   ARG H N  </span> 1
+ ATOM   <b>1034</b> N <span class="orange-fg">N   <span class="blue-bg">B</span> ARG B</span> 2  <span class="orange-fg">73</span>  <span class="blue-bg">A</span> -4.641  24.646  -55.195 0.82 22.07 ? <span class="blue-bg">77   ARG H N  </span> 1
  </pre></div>
 
 and a couple lines from another file (6any):
 
 .. raw:: html
 
- <div class="highlight"><pre style="color:#444">
- ATOM   <b>1   </b> N <span style="color:#d50">N   <span style="background-color:#ace">.</span> PHE A</span> 1 <span style="color:#d50">1  </span> <span style="background-color:#ace">?</span> 21.855 30.874 0.439  1.00 29.16 ? <span style="background-color:#ace">17  PHE A N  </span> 1 
- ATOM   <b>2   </b> C <span style="color:#d50">CA  <span style="background-color:#ace">.</span> PHE A</span> 1 <span style="color:#d50">1  </span> <span style="background-color:#ace">?</span> 20.634 31.728 0.668  1.00 26.60 ? <span style="background-color:#ace">17  PHE A CA </span> 1
+ <div class="highlight raw"><pre>
+ ATOM   <b>1   </b> N <span class="orange-fg">N   <span class="blue-bg">.</span> PHE A</span> 1 <span class="orange-fg">1  </span> <span class="blue-bg">?</span> 21.855 30.874 0.439  1.00 29.16 ? <span class="blue-bg">17  PHE A N  </span> 1 
+ ATOM   <b>2   </b> C <span class="orange-fg">CA  <span class="blue-bg">.</span> PHE A</span> 1 <span class="orange-fg">1  </span> <span class="blue-bg">?</span> 20.634 31.728 0.668  1.00 26.60 ? <span class="blue-bg">17  PHE A CA </span> 1
 
- ATOM   <b>1630</b> C <span style="color:#d50">CD2 <span style="background-color:#ace">.</span> LEU A</span> 1 <span style="color:#d50">206</span> <span style="background-color:#ace">?</span> 23.900 18.559 1.006  1.00 16.97 ? <span style="background-color:#ace">222 LEU A CD2</span> 1 
- HETATM <b>1631</b> C <span style="color:#d50">C1  <span style="background-color:#ace">.</span> NAG B</span> 2 <span style="color:#d50">.  </span> <span style="background-color:#ace">?</span> 5.126  22.623 37.322 1.00 30.00 ? <span style="background-color:#ace">301 NAG A C1 </span> 1 
- HETATM <b>1632</b> C <span style="color:#d50">C2  <span style="background-color:#ace">.</span> NAG B</span> 2 <span style="color:#d50">.  </span> <span style="background-color:#ace">?</span> 5.434  21.608 38.417 1.00 30.00 ? <span style="background-color:#ace">301 NAG A C2 </span> 1
+ ATOM   <b>1630</b> C <span class="orange-fg">CD2 <span class="blue-bg">.</span> LEU A</span> 1 <span class="orange-fg">206</span> <span class="blue-bg">?</span> 23.900 18.559 1.006  1.00 16.97 ? <span class="blue-bg">222 LEU A CD2</span> 1 
+ HETATM <b>1631</b> C <span class="orange-fg">C1  <span class="blue-bg">.</span> NAG B</span> 2 <span class="orange-fg">.  </span> <span class="blue-bg">?</span> 5.126  22.623 37.322 1.00 30.00 ? <span class="blue-bg">301 NAG A C1 </span> 1 
+ HETATM <b>1632</b> C <span class="orange-fg">C2  <span class="blue-bg">.</span> NAG B</span> 2 <span class="orange-fg">.  </span> <span class="blue-bg">?</span> 5.434  21.608 38.417 1.00 30.00 ? <span class="blue-bg">301 NAG A C2 </span> 1
 
- HETATM <b>1709</b> O <span style="color:#d50">O   <span style="background-color:#ace">.</span> HOH I</span> 6 <span style="color:#d50">.  </span> <span style="background-color:#ace">?</span> -4.171 14.902 2.395  1.00 33.96 ? <span style="background-color:#ace">401 HOH A O  </span> 1 
- HETATM <b>1710</b> O <span style="color:#d50">O   <span style="background-color:#ace">.</span> HOH I</span> 6 <span style="color:#d50">.  </span> <span style="background-color:#ace">?</span> 9.162  43.925 8.545  1.00 21.30 ? <span style="background-color:#ace">402 HOH A O  </span> 1
+ HETATM <b>1709</b> O <span class="orange-fg">O   <span class="blue-bg">.</span> HOH I</span> 6 <span class="orange-fg">.  </span> <span class="blue-bg">?</span> -4.171 14.902 2.395  1.00 33.96 ? <span class="blue-bg">401 HOH A O  </span> 1 
+ HETATM <b>1710</b> O <span class="orange-fg">O   <span class="blue-bg">.</span> HOH I</span> 6 <span class="orange-fg">.  </span> <span class="blue-bg">?</span> 9.162  43.925 8.545  1.00 21.30 ? <span class="blue-bg">402 HOH A O  </span> 1
  </pre></div>
 
 .. role:: orange_fg

docs/requirements.txt

@@ -1,2 +1,2 @@
-sphinx_rtd_theme >= 1.0.0
-sphinx >= 5.3.0
+sphinx >= 8.1.3
+furo >= 2024.8.6

run-tests.sh

@@ -49,7 +49,8 @@ grep :: $BUILD_DIR/py/gemmi/*.pyi ||:
 
 if [ -z "${NO_DOCTEST-}" ]; then
     # 'make doctest' works only if sphinx-build was installed for python3.
-    (cd docs && make doctest SPHINXOPTS="-q -n")
+    #(cd docs && make doctest SPHINXOPTS="-q -n")
+    (cd docs && $PYTHON -m sphinx -M doctest . _build -q -n)
 fi
 
 # Usually, we stop here. Below are more extensive checks below that are run