Go live with new Fedora Legal documentation

Hi,
Richard Fontana and I have been working on a refresh/rewrite of the various legal or licensing related content in the wiki to move it to Fedora Docs. (this corresponds with the new Fedora licensing data repo and adoption of SPDX ids in the license field as well - see Changes/SPDX Licenses Phase 1 - Fedora Project Wiki

The Fedora-legal documentation currently still under development is in Gitlab here: modules/ROOT · main · fedora / Fedora Legal / Fedora Legal Documentation · GitLab - how do we get it in the queue to go live, preferably on July 25th or 26th (if we can choose a date)?

Thanks!
Jilayne

@ref @mattdm for awareness

3 Likes

I’ll add it to the staging environment tomorrow so that we can verify that it all builds correctly. I’ll add it to the prod environment on the 25th or 26th.

1 Like

awesome, thanks Ben!

speaking of building correctly… there are a bunch of files and maybe a couple folder that are part of the template which are not in use. Should I delete anything of that nature - particularly files (maybe not folders, just in case they are needed later)?

1 Like

You can remove them if you want to make things cleaner, but it will build just fine if you don’t.

I can also set you up with Gitlab CI if you want. It can help you make sure your doc builds correctly and gives you a preview website to check if everything looks good before going live.

2 Likes

I just pushed the configuration. It will be available at https://docs.stg.fedoraproject.org/en-US/fedora-legal-docs at the next rebuild (in an hour or two).

I might suggest changing the name in antora.yml to be “legal” so that the URL is /legal. That’s not a huge deal, so if you want to keep it as-is, that’s fine too.

oh! that is… sooner than our date… I guess I can go put a note saying “still under construction” right now!!

I don’t think there is an antora.yml file in the repo??

It’s just on the staging instance so you can see it live and debug. I won’t put it on production until the date you requested, like I said.

The antora.yml file is in the repo at antora.yml · main · fedora / Fedora Legal / Fedora Legal Documentation · GitLab

ah, ok, phew! thanks!

oh, so you mean change the name of the repo, currently fedora-legal-docs to just legal because that essentially creates part of the URL for the actual published pages? is that right?
→ nevermind, I changed it in the antora.yml file as you said, got confused, I think that’s all I have to do then?

just looked at the staging instance- cool, that’s helpful to check stuff!! :slight_smile:

That commit you just pushed is exactly what I was suggesting. Since it’s not fully published yet, we can change that at will. Once we start sharing links publicly, we’ll want to keep it stable.

so, if the links (to external sites, and to other legal-docs pages) “work” in staging, can I assume they will work once live?

That’s right!

a couple formatting questions, if I may…

  1. is there a way to have non-linkable headings in the nav file? or at least a line break to separate one area of topics from another?

  2. is there a way to NOT have an extra line in between bulleted list items? (seems like this is a style set at the top level?)

In nav.adoc

** xref:virtualization-vm-management-cockpit.adoc[Managing virtual machines with Cockpit]
* xref:server-containerization.adoc[Containerization]
** xref:container-nspawn-install.adoc[Container systemd-nspawn – Installation]
* Providing services
** xref:service-postgresql-installation.adoc[PostgreSQL – Installation]
* Example Use Cases
** xref:usecase-gui-addon.adoc[Adding a graphical user interface]
* xref:server-faq.adoc[FAQ]

“Example Use Cases” and “Providing services” are kind of “Subheaders’” without an underlying link.

As far as I know: no (I would like to have that option, too). But there is a chance that some Antorra options exist or could get created (e.g. by @darknao).

We can lower (or remove) the line spaces for list items, but this is a global settings, so it will apply to all other documentation pages.
As long as it doesn’t affect the readability of the documentation, I’m ok with that change.

I’m unsure if that might not be a little too “courageous”. An unknown number of articles may depend on the current properties. And we may break the intended layout.

Thanks @pboy - I’ll use that method, no need to change the styles for the whole site on the line break question!

I just pushed the update to prod. The legal docs will be on docs.fp.o in the next rebuild. However, I didn’t add it to the front page or to any other navigation because I’m not quite sure where it fits. I’m open to suggestion.

oh my!
so that means, it will be visible in… an hour or so??

not sure about navigation on front page either… you are referring to the blue boxes on the Fedora docs home page?

@ref @dcantrell - heads up!