adding some minor fixes to main page of docs

CONTRIBUTING.md

@@ -69,6 +69,17 @@ python3 build-tools/docs.py
 
 The output will be in `docs-test`. For more options, run `python build-tools/docs.py --help`.
 
+> [!NOTE]
+> Since the documentation build process is relying on the working `mmif` package, one must "build" the package first before building the documentation. This can be done by running
+> ```bash
+> rm VERSION*                     # remove existing VERSION file if exists
+> make devversion                 # creates a dummy VERSION file
+> pip install -r requirements.dev # install dev dependencies
+> python setup.py sdist           # build the package (will download auto-generate subpackges like `mmif.res` and `mmif.ver`)
+
+> [!NOTE]
+> running `build-tools/docs.py` in "local testing" mode will overwrite any existing VERSION file with a dummy version.
+
 ### API Documentation (autodoc)
 
 As of 2026 (since the next version of 1.2.1), API documentation is **automatically generated** using `sphinx-apidoc`. When you run the documentation build:

documentation/conf.py

@@ -226,7 +226,7 @@ def generate_whatsnew_rst(app):
     if not found_version:
         logger.info(f"No changelog entry found for version {version}")
         with open(output_path, 'w') as f:
-            f.write("")
+            f.write(f"### nothing new in {version}\nDid you locally build for testing?")
     else:
         # Dump matched markdown content directly to whatsnew.md
         with open(output_path, 'w') as f:
@@ -261,7 +261,7 @@ def run_apidoc(app):
             *exclude_paths,
             '--force',          # Overwrite existing files
             '--module-first',   # Put module docs before submodule docs
-            '--no-toc',         # Don't create modules.rst (we maintain our own)
+            '--no-toc',         # Don't create modules.rst, will be overwriting each other's
         ]
         logger.info(f"Running sphinx-apidoc with args: {args}")
         apidoc_main(args)

documentation/index.rst

@@ -1,17 +1,17 @@
-mmif-python
-===========
+MMIF Python SDK
+===============
 
 This is the documentation for the mmif-python package, a Python implementation for the MultiMedia Interchange Format (MMIF). MMIF is a JSON(-LD)-based data format designed for transferring annotation data between computational analysis applications of the CLAMS project. For descriptions of the CLAMS project and the MMIF format see https://clams.ai and https://mmif.clams.ai. The GitHub repository for the package is at https://github.com/clamsproject/mmif-python.
 
-.. mdinclude:: whatsnew.md
+----
 
+.. mdinclude:: whatsnew.md
 
-Contents
---------
+----
 
 .. toctree::
   :maxdepth: 2
-  :caption: General documentation
+  :caption: Contents
 
   introduction
   cli
@@ -21,8 +21,10 @@ Contents
 
 .. toctree::
   :maxdepth: 2
+  :caption: API Documentation
 
-  modules
+  autodoc/mmif
+  autodoc/mmif_docloc_http
 
 
 Indices

documentation/introduction.rst

@@ -88,7 +88,7 @@ To get subcomponents, you can use various getters implemented in subclasses. For
           # do something with the video file
 
 
-For a full list of available helper methods, please refer to :ref:`the API documentation <apidoc>`. 
+For a full list of available helper methods, please refer to the API documentation pages (See left sidebar).
 
 
 MMIF usage in CLAMS Workflows