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

Discussion:
codecov[bot]: ## [Codecov](https://app.codecov.io/gh/linkml/linkml/pull/1709?src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=linkml) Report
All modified and coverable lines are covered by tests :white_check_mark:
> Comparison is base [(`598376c`)](https://app.codecov.io/gh/linkml/linkml/commit/598376ce7f8c11bd3cf31f0ca7e3d5c34770021a?el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=linkml) 79.86% compared to head [(`04cad56`)](https://app.codecov.io/gh/linkml/linkml/pull/1709?src=pr&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=linkml) 79.69%.

<details><summary>Additional details and impacted files</summary>


```diff
@@            Coverage Diff             @@
##             main    #1709      +/-   ##
==========================================
- Coverage   79.86%   79.69%   -0.18%     
==========================================
  Files          98       98              
  Lines       11185    11103      -82     
  Branches     2865     2811      -54     
==========================================
- Hits         8933     8848      -85     
- Misses       1716     1718       +2     
- Partials      536      537       +1     
```


| [Files](https://app.codecov.io/gh/linkml/linkml/pull/1709?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=linkml) | Coverage Δ | |
|---|---|---|
| [linkml/generators/docgen.py](https://app.codecov.io/gh/linkml/linkml/pull/1709?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=linkml#diff-bGlua21sL2dlbmVyYXRvcnMvZG9jZ2VuLnB5) | `84.50% <100.00%> (-0.11%)` | :arrow_down: |

... and [18 files with indirect coverage changes](https://app.codecov.io/gh/linkml/linkml/pull/1709/indirect-changes?src=pr&el=tree-more&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=linkml)


</details>

[:umbrella: View full report in Codecov by Sentry](https://app.codecov.io/gh/linkml/linkml/pull/1709?src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=linkml).   
:loudspeaker: Have feedback on the report? [Share it here](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=linkml).

sujaypatil96: This is a good solution to allow users to specify the name of the index markdown file that is generated alongside the LinkML schema element markdown documentation pages, i.e., allow the option of calling it something other than `index.md` which is currently the default (and only option).

However, it is also important to keep in mind, the [linkml-project-cookiecutter](https://github.com/linkml/linkml-project-cookiecutter) repo which is what the LinkML community recommends you start off with while creating a new LinkML schema. The cookiecutter creates a project directory structure for you which includes an `mkdocs.yml` file, and the index/landing page is "hardcoded" in the mkdocs.yml file on this line: https://github.com/linkml/linkml-project-cookiecutter/blob/main/%7B%7Bcookiecutter.project_name%7D%7D/mkdocs.yml#L15

At the very least we should make a _note_ on our documentation page for the markdown generator: https://linkml.io/linkml/generators/markdown.html that users will need to change the name of their index file in mkdocs.yml if they've created their schema repos using thecookiecutter.
cmungall: Thanks @sujaypatil96! I made an issue on cookiecutter

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