docs: support building a subset of the documentation with build_docs

Closes IDF-1688

docs/idf_extensions/exclude_docs.py

@@ -1,10 +1,43 @@
+from sphinx.util import get_matching_files
+from sphinx.util.matching import compile_matchers
+
+
 # Updates the excluded documents according to the conditional_include_dict {tag:documents}
 def update_exclude_patterns(app, config):
+
+    # Default to building all if option not set
+    if config.docs_to_build:
+        build_subset(app, config)
+
     for tag, docs in config.conditional_include_dict.items():
         if not app.tags.has(tag):
             app.config.exclude_patterns.extend(docs)
 
 
+def build_subset(app, config):
+    # Convert to list of docs to build
+    docs_to_build = config.docs_to_build.split(',')
+
+    # Exclude all documents which were not set as docs_to_build when build_docs were called
+    exclude_docs = [filename for filename in get_matching_files(app.srcdir, compile_matchers(docs_to_build))]
+    docs = [filename for filename in get_matching_files(app.srcdir, compile_matchers(exclude_docs))]
+
+    app.config.exclude_patterns.extend(exclude_docs)
+
+    # Get all docs that will be built
+    docs = [filename for filename in get_matching_files(app.srcdir, compile_matchers(exclude_docs))]
+    if not docs:
+        raise ValueError("No documents to build")
+    print("Building a subset of the documents: {}".format(docs))
+
+    # Sphinx requires a master document, if there is a document name 'index' then we pick that
+    index_docs = [doc for doc in docs if 'index' in doc]
+    if index_docs:
+        config.master_doc = index_docs[0].replace('.rst', '')
+    else:
+        config.master_doc = docs[0].replace('.rst', '')
+
+
 def setup(app):
     # Tags are generated together with defines
     app.connect('config-inited', update_exclude_patterns)