Migrate announcements page to news/

[jaimergp]

PR Checklist:

• note any issues closed by this PR with closing keywords
• put any other relevant information below

See #1971 (comment).

I split the announcements.rst page in individual pages and put them all together under news/. I've left a reference to the originating PRs where relevant, along with the coauthorship, in each commit. I've chosen to list 10 announcements per page, although we can technically render all of them if we wish (by setting the perPagePosts value to ALL).

The RSS feed is now generated by Docusaurus so I removed our custom machinery. There's only one gotcha and it's that the redirect plugin doesn't cover static assets like the RSS XML, so we just copy it in place in the build script so the old link still works.

Script used to split the single announcements.rst into multiple markdowns

from subprocess import check_output

with open("announcements.rst") as f:
    lines = f.readlines()
lines.append("\n")
lines.append("\n")

docs = {}
title = None
for i, line in enumerate(lines):
    if i == 0:
        continue
    previous = lines[i - 1].strip()
    if "^^^^" in line:
        title = lines[i - 1].strip()
        continue
    if "^^^^" in previous:
        continue
    if not title:
        continue
    docs.setdefault(title, []).append(previous)

for title, rst_lines in docs.items():
    slug = title.lower().replace(" ", "-").replace("+", "-")
    for char in "`:()/!?',.”…‘”“*_<>#&":
        slug = slug.replace(char, "")
    slug = slug.replace("--", "-").replace("--", "-")
    date, header = title.split(":", 1)
    header = header.strip()
    md_content = check_output(["pandoc", "-f", "rst", "-t", "gfm"], text=True, input="\n".join(rst_lines))
    md_content = md_content.strip().replace("\n\n", "\n").replace("\\", "")
    with open(f"{slug}.md", "w") as f:
        f.write(f"# {header}\n\n{md_content}\n")

[beckermr]

@jaimergp do the links to single announcements still work? For example, links like this: https://conda-forge.org/docs/user/announcements.html#python-3-12-migration-and-python-3-11-by-default

[jaimergp]

https://conda-forge.org/docs/user/announcements.html will redirect to https://conda-forge.org/news. No clue what happens with the anchors. Let me see if there's a way to hack something simple together.

Edit: Ok, the #anchor bit is kept after the redirect (we land in https://conda-forge.org/news##python-3-12-migration-and-python-3-11-by-default) but nothing really happens because the target headers do not have ids. So, we can:

• Ignore the anchors and leave it as is :D
• Redirect /docs/user/announcements.html to /news/archive so folks will see a full list of announcements and try to infer which one was meant by the old anchor
• Redirect /docs/user/announcements.html to /news/ (no archive) and configure this component to list ALL announcements without pagination. This way users will see all announcements at once and can Ctrl+F their way to the correct one.
• Export an orphan page redirected_announcements.md or something where we redirect to from /docs/user/announcements.html. In there we will publish a list of links to the new locations, with the appropriate anchors.

[beckermr]

Well I'd really like each item to have its own link so that we can refer to specific items directly when communicating with folks.

The current blog has links per post. Is there a reason that format would not work here?

[jaimergp]

Yes, sorry, I misunderstood. Each announcement will have its own permalink of course. They are their own "post" with a URL. See the "single announcement" screenshot in #1971 (comment). What I didn't implement is a forwarder from announcements.html#some-announcement to news/some-announcement/.

[beckermr]

Ahhhh. At least for the old announcements I think we want the links to forward. For future announcements we won't need that.

[beckermr]

A single static orphan page at the right location would be fine.

[jaimergp]

Added /announcements/ with the same anchor links (see bottom right corner for an example). The old /docs/user/announcements.html will redirect there.

[beckermr]

Perfect! Thank you!

[beckermr]

The only other page that I think will need redirects is the getting in touch page. The rest of the docs can change without us worrying.

[jaimergp]

@beckermr, if you meant these links, they have been updated too so they point to the new URLs 🚀

[beckermr]

Sorry I mean this link https://conda-forge.org/docs/orga/getting-in-touch.html#getting-in-touch when it gets moved over in future PRs. I should have put my comment in the main issue.

[beckermr]

I will merge this afternoon if no more comments come in.

[jakirkham]

Thanks Jaime! 🙏

Will take a closer look in a moment

At first pass a few things stick out to me, this change could make the commit history harder to navigate. We may want to ignore this commit

Also this creates a lot of files as each announcement is broken out. Maybe that is ok as we do the agenda this way and it could make it easier to add a new item. Though it could complicate finding an item. We might also want to lint names to ensure they match whatever format we expect

Was there a preview link somewhere? Looked through the PR, but maybe I missed it

[beckermr]

The multiple files is way better IMHO.

[jakirkham]

Was there a preview link somewhere? Looked through the PR, but maybe I missed it

Any thoughts on this question? Will need this to finish reviewing

[jaimergp]

We have no preview links in GH Pages. We could set a Netlify account for conda-forge just for the previews but I haven't bothered yet. I could also commit this to cf-infra-docs.

For now, you can render locally though:

conda env create -n name cf-docusaurus -f .ci_scripts/environment.yml
conda activate cf-docusaurus
.ci_scripts/update_docs
python -m http.server -d build

Typed that on my phone so some paths might be wrong but you get the idea :)

[jaimergp]

Alternatively, you can extract this tarball and preview it with python -m http.server -d build:

build.tar.gz

[jaimergp]

We might also want to lint names to ensure they match whatever format we expect

The filename is not super strict. Docusaurus supports several schemes, and it can be overridden in the frontmatter.
I'm assuming folks will just mimic whatever they find in each section. I'm planning to document all of this in a "Contributing to the website" guide, once we're done with the migration (or at least when we are no longer serving raw Sphinx).

[beckermr]

I agree. We don't need a specific lint for this.

[jaimergp]

@jakirkham, is this ok to go or do you still want to add some feedback? Thanks! 🙏

[jakirkham]

I'm sorry Jaime. Got clobbered with work tasks this week. Will pick this up Monday next week

[jaimergp]

Sorry to ping again @jakirkham. I understand you might be busy with other higher prio tasks, but if that's ok, I'd like to move forward with this and we can revisit your feedback once it goes live. We made extra sure no links are broken so I think there's no risk in just going with it. We can adjust things later if needed. Wdyt?

[beckermr]

LGTM for going ahead!

[jakirkham]

I'm so sorry Jaime 😞

Please go ahead without me. Maybe I can look at what is produce on the webpage and we can discuss after