Add a Related Projects element in the documentation sidebar

[settermjd]

Feature Request

Q	A
New Feature	yes
RFC	no
BC Break	no

Summary

After my recent experience, this week, with some of the various sub-projects’ documentation, I’m keen to help improve what I see as some glaring oversights. Quoting @froschdesign, "Unfortunately, the documentation is very fragmented and difficult to comprehend here." I absolutely agree, and that’s what I experienced.

What I’m propose is to go through the documentation, starting with Mezzio Authentication, and add a supplementary section in the right-hand side sidebar, one that links a given project to any directly related ones. You can see a mockup in the attached image below, in the bottom right-hand corner, labelled "Related Projects".

This would require changes to the MkDocs template, and time to update as many of the related projects as possible. However, I believe that it would be worth doing, to help others avoid the same confusion and frustration that I experienced.

[froschdesign]

@settermjd
This is definitely a quick and easy solution! 👍

But I don't know if the headline "Related Projects" is meaningful enough. In the example mezzio-authentication the "related projects" are adapters but this is not clear from the headline. A similar example can be found under laminas-mvc and the controller plugins.
But a list at the bottom of a page is definitely too little and is quickly overlooked.

The technical implementation of this feature is relatively simple. We already use some extensions like:

• Versions
• Special homepage
• Installation page
• Installation command

I can also take over the implementation here.

---

Another idea is to merge the documentation of the sub-projects via Git Submodules – but this is an unpopular way.

[arueckauer]

First of all, thank you for putting the time and effort in to improve what might have caused some frustration for you. That is a very selfless and helpful approach. 😊

You mentioned some difficulties while implementing some feature pertaining to authentication or session handling. As I don't know what the difficulty was, I am not sure, if a reference in the sidebar would solve this particular issue for future users. Hence I am wondering if a more descriptive description might be an even better solution. Other Laminas components describe what is part of said component and if the user has need of an enhancing feature X they should have a look at component Y.

So, maybe it is even a combination of a more prominent position in the sidebar and a description?

[froschdesign]

@arueckauer
See also #18

[settermjd]

@settermjd
This is definitely a quick and easy solution! 👍

But I don't know if the headline "Related Projects" is meaningful enough. In the example mezzio-authentication the "related projects" are adapters but this is not clear from the headline. A similar example can be found under laminas-mvc and the controller plugins.
But a list at the bottom of a page is definitely too little and is quickly overlooked.

The technical implementation of this feature is relatively simple. We already use some extensions like:

* [Versions](https://github.com/mezzio/mezzio/blob/7d71a4887fb0a4dc99e39dd7c4a79fea2bb36170/mkdocs.yml#L6-L10)

* [Special homepage](https://github.com/mezzio/mezzio/blob/7d71a4887fb0a4dc99e39dd7c4a79fea2bb36170/mkdocs.yml#L5)

* [Installation page](https://github.com/laminas/laminas-i18n/blob/99519a72c3a38ab0522df332a732841517c16332/mkdocs.yml#L48-L52)

* [Installation command](https://github.com/laminas/laminas-coding-standard/blob/d72d4c57d455959872cba2cefd0eb06ce7b6bef9/mkdocs.yml#L9-L10)

I can also take over the implementation here.

Another idea is to merge the documentation of the sub-projects via Git Submodules – but this is an unpopular way.

Hey @froschdesign, I agree that it's not a massive change (and thanks for the feedback on the proposed title), however, my intent is to make a number of smaller steps to progressively improve the documentation, ones that we can test relatively quickly quickly, and get people and the wider community used to. Thanks for taking over the implementation.

[settermjd]

Hey @arueckauer, thanks for your feedback. I hope that what I wrote didn't come across as some form of a narky rant. I was frustrated, yes, but I hope that I put myself across in a constructive way. I like your point about being more conspicuous. My intent with this PR was really just to be a small start along the road to a more comprehensive solution. As I said to @froschdesign, I see the changes from this PR mainly as but one part of a larger solution.

[froschdesign]

@settermjd
I have created a simple variant which uses the extra section of the MkDocs configuration file. See: laminas/documentation-theme#60

[froschdesign]

@settermjd
An example can be found in the documentation of laminas-i18n: https://docs.laminas.dev/laminas-i18n/view-helpers/translate-plural/#using-locale