Repository: linkml/linkml

Issue:
`gen-doc` should allow renaming the index page
**Is your feature request related to a problem? Please describe.**
The `gen-doc` tool automatically generates an index page for the documentation it generates. That page is always named `index.html`. This is annoying as most web servers are configured by default to return `index.html` to a client that asks for a directory index.

This means, for example, that when someone visits the [website for SSSOM](https://mapping-commons.github.io/sssom/) (which is partially generated by LinkML), the page the visitor lands on first is the LinkML index, which is not very informative – the visitor then needs to manually go to the [“home” page](https://mapping-commons.github.io/sssom/home/) to learn what SSSOM actually is.

**Describe the solution you'd like**
I would like a way to change the default behaviour of `gen-doc` so that the auto-generated index page may be named differently. For example, a command-line option as follows:

```sh
gen-doc --index-name schema-index ...
```

which would lead `gen-doc` to write the index in a file named `schema-index.html` instead of `index.html`.

**How important is this feature?** Select from the options below:
• Low - it's an enhancement but not crucial for work

There are at least two possible workarounds:

* changing the configuration of the web server to use a different filename for the directory index (not always possible depending on where and how the website is hosted);
* forcibly rename the generated `index.html` to something else and replace it with the intended home page after the `gen-doc` run (would work everywhere but definitely not ideal).

**When will use cases depending on this become relevant?** Select from the options below:
• Short-term - 2-4 weeks

Comments:

Patch:
diff --git a/linkml/generators/docgen.py b/linkml/generators/docgen.py
index c7d04a89..0dee9da8 100644
--- a/linkml/generators/docgen.py
+++ b/linkml/generators/docgen.py
@@ -130,6 +130,9 @@ class DocGenerator(Generator):
     directory: str = None
     """directory in which to write documents"""
 
+    index_name: str = "index"
+    """name of the index document"""
+
     template_directory: str = None
     """directory for custom templates"""
 
@@ -188,7 +191,7 @@ class DocGenerator(Generator):
         }
         template = self._get_template("index")
         out_str = template.render(gen=self, schema=sv.schema, schemaview=sv, **template_vars)
-        self._write(out_str, directory, "index")  # TODO: make configurable
+        self._write(out_str, directory, self.index_name)
         if self._is_single_file_format(self.format):
             logging.info(f"{self.format} is a single-page format, skipping non-index elements")
             return
@@ -844,6 +847,7 @@ class DocGenerator(Generator):
     required=True,
     help="Folder to which document files are written",
 )
+@click.option("--index-name", default="index", show_default=True, help="Name of the index document.")
 @click.option("--dialect", help="Dialect or 'flavor' of Markdown used.")
 @click.option(
     "--diagram-type",
@@ -885,7 +889,7 @@ class DocGenerator(Generator):
 )
 @click.version_option(__version__, "-V", "--version")
 @click.command()
-def cli(yamlfile, directory, dialect, template_directory, use_slot_uris, hierarchical_class_view, **args):
+def cli(yamlfile, directory, index_name, dialect, template_directory, use_slot_uris, hierarchical_class_view, **args):
     """Generate documentation folder from a LinkML YAML schema
 
     Currently a default set of templates for markdown is provided (see the
@@ -912,6 +916,7 @@ def cli(yamlfile, directory, dialect, template_directory, use_slot_uris, hierarc
         template_directory=template_directory,
         use_slot_uris=use_slot_uris,
         hierarchical_class_view=hierarchical_class_view,
+        index_name=index_name,
         **args,
     )
     print(gen.serialize())


Test patch:
diff --git a/tests/test_generators/test_docgen.py b/tests/test_generators/test_docgen.py
index 01037a12..18b8e71d 100644
--- a/tests/test_generators/test_docgen.py
+++ b/tests/test_generators/test_docgen.py
@@ -4,6 +4,7 @@ Tests generation of markdown and similar documents
 Note that docgen replaces markdowngen
 """
 import logging
+import os
 from collections import Counter
 from copy import copy
 from typing import List
@@ -426,6 +427,15 @@ def test_custom_directory(kitchen_sink_path, input_path, tmp_path):
     assert_mdfile_contains(tmp_path / "Organization.md", "FAKE TEMPLATE")
 
 
+def test_gen_custom_named_index(kitchen_sink_path, tmp_path):
+    """Tests that the name of the index page can be customized"""
+    gen = DocGenerator(kitchen_sink_path, index_name="custom-index")
+    gen.serialize(directory=str(tmp_path))
+    assert_mdfile_contains(tmp_path / "custom-index.md", "# Kitchen Sink Schema")
+    # Additionally test that the default index.md has NOT been created
+    assert not os.path.exists(tmp_path / "index.md")
+
+
 def test_html(kitchen_sink_path, input_path, tmp_path):
     """
     Tests ability to specify a complete new set of templates in a different format