✨ add bigbio/docs/output.md to documentation for releae 1.5.0

README.md

@@ -28,5 +28,7 @@ Run the following command inside the `docs` folder to build the HTML:
 
 ```bash
 # build page in docs folder
+python setup_docs.py # downloads files from bigbio/quantms/docs folder, 
+                     # called in conf.py if built on Read The Docs.
 sphinx-build -n -W --keep-going -b html ./ ./_build/
 ```

docs/.gitignore

@@ -0,0 +1,4 @@
+# build artifacts
+_build
+# downloaded from bigbio/quantms
+quantms_output.md

docs/conf.py

@@ -10,7 +10,8 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
+import os
+
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
@@ -22,7 +23,7 @@
 author = 'daichengxin, jpfeuffer, timosachenberg, ypriverol'
 
 # The full version, including alpha/beta/rc tags
-release = '1.4.0'
+release = '1.5.0'
 
 
 # -- General configuration ---------------------------------------------------
@@ -31,6 +32,9 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "sphinx_new_tab_link",
+    "myst_nb",
+    "sphinx_copybutton",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -55,3 +59,17 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+
+if os.environ.get("READTHEDOCS") == "True":
+    # If we are building on ReadTheDocs, we need to download the output file
+    # from the GitHub repository.
+    def download_files(_):
+        from setup_docs import download_output
+
+        # Download the output file
+        download_output()
+
+    def setup(app):
+        # on extensions, see:
+        # https://www.sphinx-doc.org/en/master/usage/extensions/index.html
+        app.connect("builder-inited", download_files)

docs/index.rst

@@ -16,6 +16,7 @@ Contents
    usage
    introduction
    formats
+   quantms_output
    preprocessing
    identification
    dda

docs/setup_docs.py

@@ -0,0 +1,55 @@
+import requests
+
+OUTPUT_URL = (
+    "https://github.com/bigbio/quantms/raw/refs/heads/README_links/docs/output.md"
+)
+
+
+def download_file(url, save_path, timeout=20):
+    """
+    Download a file from a URL and save it to the specified path.
+
+    Args:
+        url (str): URL of the file to download
+        save_path (str): Path where the downloaded file will be saved
+        timeout (int): Timeout for the download request in seconds
+
+    Returns:
+        bool: True if download was successful, False otherwise
+    """
+
+    # Send GET request
+    response = requests.get(url, stream=True, timeout=timeout)
+    response.raise_for_status()  # Raise exception for HTTP errors
+
+    # Write content to file
+    with open(save_path, "wb") as f:
+        for chunk in response.iter_content(chunk_size=8192):
+            f.write(chunk)
+
+    print(f"Successfully downloaded: {url} to {save_path}")
+    return True
+
+
+def download_output(output_path="quantms_output.md"):
+    """
+    Download the output file from the specified URL and save it locally to use
+    for Sphinx documentation purposes.
+    """
+    # new folders would need to be created if necessary
+
+    assert download_file(OUTPUT_URL, output_path)  # prints success message
+
+    with open(output_path, "r") as f:
+        content = f.readlines()
+
+    assert len(content) > 0, "Downloaded file is empty"
+
+    content[0] = "# quantms outputs\n"
+
+    with open(output_path, "w") as f:
+        f.writelines(content)
+
+
+if __name__ == "__main__":
+    download_output()

requirements.txt

@@ -1,2 +1,5 @@
 sphinx
 furo
+myst-nb
+sphinx-new-tab-link
+sphinx-copybutton