Merge pull request #521 from padix-key/doc

Second attempt on image scraper fixing

.github/workflows/test_and_deploy.yml

@@ -192,15 +192,15 @@ jobs:
     - name: Install distribution
       run: pip install .//dist//*.whl
     - name: Build base documentation
-      run: sphinx-build -D plot_gallery=0 doc build//doc
+      run: sphinx-build -a -D plot_gallery=0 doc build//doc
     - name: Build tutorial and gallery
       if: >
         (
           github.event_name == 'release' &&
           github.event.action == 'published'
         )
         || github.event_name == 'workflow_dispatch'
-      run: sphinx-build doc build//doc
+      run: sphinx-build -a doc build//doc
     - name: Zip documentation
       run: |
           cd build

doc/conf.py

@@ -164,7 +164,7 @@
     "doc_module"                : ("biotite",),
     # Set the NCBI API key
     "reset_modules"             : (key.set_ncbi_api_key_from_env,),
-    "remove_config_comments"    : False,
+    "remove_config_comments"    : True,
 }
 
 

doc/contribute.rst

@@ -188,7 +188,7 @@ corresponding code block:
 
 .. code-block:: python
 
-   # biotite_static_image = <name_of_the_image>.png
+   # sphinx_gallery_static_image = <name_of_the_image>.png
 
 The image file must be stored in the same directory as the example script.
 
@@ -203,10 +203,10 @@ The visualization is initiated by adding the comment line
 
 .. code-block:: python
 
-   # Visualization with PyMOL..
+   # sphinx_gallery_ammolite_script = <name_of_the_script>.py
 
 in the code block where you want show the visualization.
-Then the visualization script ``<example_name>_pymol.py`` is executed, which
+Then the visualization script ``<name_of_the_script>.py`` is executed, which
 can use the global variables from the example script and the special
 ``__image_destination__`` variable.
 ``__image_destination__`` is a string representing the path to the output image

doc/examples/scripts/structure/biological_assembly.py

@@ -75,6 +75,6 @@
 temp = NamedTemporaryFile(suffix=".cif")
 strucio.save_structure(temp.name, biological_unit)
 # Visualization with PyMOL...
-# sphinx_gallery_pymol_image
+# sphinx_gallery_ammolite_script = "biological_assembly_pymol.py"
 
 temp.close()

doc/examples/scripts/structure/contact_sites.py

@@ -78,4 +78,4 @@
     print(res_name.capitalize() + str(res_id))
 
 # Visualization with PyMOL...
-# sphinx_gallery_pymol_image
+# sphinx_gallery_ammolite_script = "contact_sites_pymol.py"

doc/examples/scripts/structure/docking.py

@@ -148,4 +148,4 @@
 
 # Visualization with PyMOL...
 # sphinx_gallery_thumbnail_number = 2
-# sphinx_gallery_pymol_image
+# sphinx_gallery_ammolite_script = "docking_pymol.py"

doc/examples/scripts/structure/leaflet.py

@@ -112,6 +112,6 @@ def find_leaflets(structure, head_atom_mask,
 temp = NamedTemporaryFile(suffix=".pdb")
 strucio.save_structure(temp.name, structure)
 # Visualization with PyMOL...
-# sphinx_gallery_pymol_image
+# sphinx_gallery_ammolite_script = "leaflet_pymol.py"
 
 temp.close()

doc/examples/scripts/structure/peptide_assembly.py

@@ -253,6 +253,6 @@ def assemble_peptide(sequence):
 out_file = NamedTemporaryFile(suffix=".mmtf", delete=False)
 strucio.save_structure(out_file.name, chain)
 # Visualization with PyMOL...
-# sphinx_gallery_pymol_image
+# sphinx_gallery_ammolite_script = "peptide_assembly_pymol.py"
 
 out_file.close()

doc/scraper.py

@@ -1,4 +1,3 @@
-from glob import glob
 import shutil
 import copy
 import sys
@@ -10,7 +9,7 @@
 
 
 STATIC_IMAGE_COMMAND = "static_image"
-PYMOL_IMAGE_COMMAND = "pymol_image"
+PYMOL_IMAGE_COMMAND = "ammolite_script"
 
 
 def static_image_scraper(block, block_vars, gallery_conf):
@@ -51,7 +50,8 @@ def pymol_scraper(block, block_vars, gallery_conf):
     if PYMOL_IMAGE_COMMAND not in block_conf:
         return figure_rst([], gallery_conf['src_dir'])
 
-    pymol_script_path = splitext(block_vars["src_file"])[0] + "_pymol.py"
+    script_dir = dirname(block_vars["src_file"])
+    pymol_script_path = join(script_dir, block_conf[PYMOL_IMAGE_COMMAND])
     # The rendered image will be created in the same directory as
     # the example script
     # -> the image will be included in version control