Use docs/docsite/links.yml file to create extra links

[felixfontein]

WIP implementation for ansible-collections/overview#181 using https://gist.github.com/felixfontein/18b1763ca2a5320808225c4121b50791. See ansible-collections/community.dns#76 for how such a file can look like, and:

• https://ansible.fontein.de/collections/community/dns/
• https://ansible.fontein.de/collections/community/dns/hetzner_dns_record_module.html#authors
• https://ansible.fontein.de/collections/community/dns/hetzner_dns_records_inventory.html#authors

for how it looks. The very first version only has a "Edit on GitHub" link on the module and plugin, but hey, that's the very first step :-)

[felixfontein]

This PR currently includes #354; will rebase once that's merged. Rebased.

[felixfontein]

Now collection metadata and extra links are extracted and shown:

• https://ansible.fontein.de/collections/community/dns/ (source: https://github.com/ansible-collections/community.dns/pull/76/files, https://github.com/ansible-collections/community.dns/blob/main/galaxy.yml)
• https://ansible.fontein.de/collections/ansible/builtin/ (the information shown here is hardcoded)

[samccann]

On the example where we highlight the author with a link to their email... seems like we need consent from each author before we do something like that.

[samccann]

We also need to make those buttons the 'ansible teal' so to speak at least on this docsite so it matches.

[felixfontein]

I've added links to the communication data supplied by the collection. (I've slightly adjusted the communication schema in https://gist.github.com/felixfontein/18b1763ca2a5320808225c4121b50791 for this, to include a topic for every channel.)

[felixfontein]

On the example where we highlight the author with a link to their email... seems like we need consent from each author before we do something like that.

In such examples, the author put their email address in the collection's authors field. I would say this is consent to display that information. (We also do that if they include email addresses in the module/plugin authors fields.)

[felixfontein]

The last commit reduces the number of buttons (Documentation is skipped; and Homepage is skipped if it equals the homepage or repository link).

[felixfontein]

We also need to make those buttons the 'ansible teal' so to speak at least on this docsite so it matches.

Done.

[felixfontein]

I updated the schema slightly (https://gist.github.com/felixfontein/18b1763ca2a5320808225c4121b50791 and https://github.com/ansible-collections/community.dns/pull/76/files are updated) to match the internal data structures, and switched to using Pydantic for parsing so I can also use it for linting. The output didn't change at all.

With the linting in place, I think this is ready for some reviewing. (I guess that the design / output needs some adjustments :) )

[briantist]

This looks really cool!

[GregSutcliffe]

Really, really nice work @felixfontein - thanks again for getting ahead of me on this!

I love the buttons, I think that works well. I guess @samccann has the last word on the look of things, but it's nice and prominent, high up the page, and clearly differenciated.

Do we need a dedicated section in the metadata for communication? I'm concerned that they get lost as text underneath the button links - the eye is drawn there and skims over the bit below. Would it not be simpler to put those links into extra_links and render them as buttons? e.g.

extra_links:
  - description: Submit a bug report
    url: https://github.com/ansible-collections/community.dns/issues/new?assignees=&labels=&template=bug_report.md
  - description: Request a feature
    url: https://github.com/ansible-collections/community.dns/issues/new?assignees=&labels=&template=feature_request.md
  - descripton: Matrix Room
    url: https://matrix.to/#/#community:ansible.com
  - description: IRC Channel
    url: https://web.libera.chat/?channel=#ansible-community

It seems unlikely that a collection would need multiple Matrix/IRC rooms, I think, but nothing is preventing it this way, you'll just get a lot of buttons. However the buttons seem to overflow nicely, so even that isn't a huge concern.

This would simplify the code (no extra handling for communication and deal with the visibility concern. Thoughts?

[samccann]

Is there something we can put on the individual module pages as well? I don't want to go overboard here, but we used to have 'edit on github' on every module page. It would be cool if we could either put a link back to the collection index page where all the buttons are, or add a the buttons to the module/plugin pages as well? I don't want to overclutter things ...

[GregSutcliffe]

Good catch @samccann - I'd agree with rendering them on the plugin pages too - they don't take up too much space as a single line (assuming the "Communication" text section is dropped) so I think clutter is minimal, and is probably a win.

People who go straight to a module/plugin from history, search, etc, might not know to head back to the index page for links - and by the time you've explained to go there for further directions, you might as well put the buttons anyway.

[felixfontein]

@GregSutcliffe

Do we need a dedicated section in the metadata for communication? I'm concerned that they get lost as text underneath the button links - the eye is drawn there and skims over the bit below. Would it not be simpler to put those links into extra_links and render them as buttons? e.g.

Personally, I would avoid that, since having too many buttons makes it hard to find the things you are looking for (you potentially have to read all of them). I would avoid having more than 3-5 buttons.

About converting the communication metadata to extra links: we would be losing all metadata on communication channels and will not have a chance to display them differently at any point in the future. If we really want to show everything as buttons, we should dynamically convert communication metadata to buttons.

It seems unlikely that a collection would need multiple Matrix/IRC rooms, I think, but nothing is preventing it this way, you'll just get a lot of buttons. However the buttons seem to overflow nicely, so even that isn't a huge concern.

In terms of IRC channels, there's always #ansible for general help/support questions, and #ansible-(something) for development questions. Which would be two IRC channels and two Matrix rooms :)

[felixfontein]

I've updated the PR to:

1. Use RTD's 'Edit on GitHub' button instead of the added note (the Ansible Sphinx theme is based on the RTD theme, so it will work there as well);
2. Show the collection links on every plugin page as well.

(I also fixed the Edit on GitHub links for community.general and community.network, where they were currently broken for modules due to the subdirectory structure.)

[felixfontein]

(Example: https://ansible.fontein.de/collections/community/dns/hetzner_dns_record_module.html#collection-links for the collection links; look at the top of the page for the 'Edit on GitHub' link.)

[samccann]

I like the Edit on Github official 'button' being back, that's great! Thanks for that @felixfontein. I wonder if we should left-justify the buttons so they don't seem so 'floating in space' so to speak?

Also on the plugin pages, do we need a link to the ...wait for it... communication links header? :-) So it's noticable at the top level toc.

[felixfontein]

@samccann how about the following changes:

1. Make 'Authors' and 'Communications' higher-level headers (and maybe even add a TOC at the top?)
2. Keep the buttons at the top below the collection's description and above extra sections
3. Add a Communication button on the collection index page as well (that goes down to the communication section, which now will be at the end of the index)

That way the "less relevant" information (authors, communication) will be at the bottom, but still visible (due to the TOC).

Regarding alignment of the buttons: I'm not sure whether I'll like them left aligned. But then, I'm not a designer. You can try out different alignments by changing the justify-content CSS property to flex-start (left-aligned) or flex-end (right-aligned) instead of its current value center for the <p class="ansible-links">.

[samccann]

With it set to flex-start -

with is set to center (current implementation)

PROPOSAL - we use flex-start (left justified). Please thumbs-up this comment if you agree or thumbs down if you want to keep it the way it is (centered)

[felixfontein]

What about these ideas?

how about the following changes:

1. Make 'Authors' and 'Communications' higher-level headers (and maybe even add a TOC at the top?)
2. Keep the buttons at the top below the collection's description and above extra sections
3. Add a Communication button on the collection index page as well (that goes down to the communication section, which now will be at the end of the index)

That way the "less relevant" information (authors, communication) will be at the bottom, but still visible (due to the TOC).

[GregSutcliffe]

OK, these inline replies are starting to get out of hand (size-wise) 😁

For all collections I'm working on there is no specific channel for them. Many questions are more regular usage questions that are based aimed at #ansible, but in some cases none of the developers/maintainers will be in #ansible, so depending on the question #ansible-community might be a better channel.
In any case, we should not define hard limits here on the minimal or maximal number of communication channels, we should only provide recommendations that collections can stick to (or ignore).

That's fair. What I'm trying to avoid is confusing people - I have been on way too many pages where it is unclear where I should go next, and I don't want to repeat that mistake. Multiple channels makes this highly likely, but I agree with the other point about setting examples rather than defining hard limits. Thus, I'd suggest sticking to a single one as the "recommended approach" - most people are friendly, and if a question is off-topic (which should be infrequent) then signposting will happen.

(It would be fair to say that linking to both Matrix and IRC falls under the same problem, but we currently commit to treating them equally, so I can't suggest dropping that 😛)

This also applies to the later point about page loads - every page load generally causes some more users to just give up. I'd rather get them talking to someone (or writing an issue, or a mailing list post, or something else interactive) sooner rather than later, which is why I lean towards duplication across pages rather than multiple loads to get to the right thing. It's not duplicated for us because we define it once in the metadata - it's just rendered in multiple places. I don't think that will cause any conflicts, right? In which case I don't understand the harm of seeing the buttons in multiple places.

It doesn't really matter whether it's my code or not, it's more important to figure out what we (as the community) want. Then I (or someone else) can implement that.

Yes, sorry, I was being flippant in my earlier statement. What I was trying to say is, you're doing the hard work right now, and I respect that, and that carries weight, regardless of who may maintain it later.

---

In any case, I feel like I'm "bikeshedding" here. All the work so far is great, and a vast improvement on the nothing we have at the moment. I'm certainly not going to make a big fuss if you ignore me entirely 😛

In the last docs meetings, @samccann suggested we just get on with it, and then get feedback from both collection owners and users in a little while, and I support that. I'd be happy to craft a small survey or something to be run a month or two after merge and get some opinions on how we can improve it. Thoughts?

[samccann]

Can't comment on the code but the output/result LGTM

[felixfontein]

Assuming there's no (negative) feedback in #80 until this evening, and assuming that @samccann and @GregSutcliffe don't veto, I'll merge this tomorrow morning.

[GregSutcliffe]

LGTM 👍

[samccann]

LGTM too

[felixfontein]

@samccann @briantist @GregSutcliffe and everyone else involved, thanks a lot for reviewing and testing this, and for all the dicussions on this one!