Proposal: Move apidocs from git to infra web

Technically you’re free to choose whatever but the default is now develop.

Wait, I will probably not use gh pages to generate the content, but Hugo via GH Actions. Our new foreman-documentation repo uses master and the GH Action pushes into gh-pages. I will probably switch to much faster Hugo to generate the index pages content.

Or alternatively we can ditch any kind of generation and only copy a single HTML page. That is probably the easiest solution - the layout and the index HTML page is actually quite simple. Then everything can be done in gh-pages branch without any tools needed.

We don’t need any generation, the generation is already done when the apidocs are created. Just plain old HTML will be fine.

Well we actually do:

As I said, it is easy to just have a HTML page instead and copy it over.

Or if you mean just to expose plain API pie, I am all for it:

https://theforeman.org/api/2.4/apidoc/v2.html

People can use back button in their browser…

1 Like

Exactly. If we’re lazy efficient, we could even use plain old HTML frames for navigation. I think we actually used to have a redirect at Index of /api but it’s now just a directory listing. Personally I’m fine with it since it works and doesn’t require maintenance. Let’s try to engineer this so it requires the least amount of maintenance while still fulfilling its purpose.

I have just removed 22 million unused lines from our theforeman.org github repository along the way:

https://github.com/theforeman/theforeman.org/pull/1807

Yeah, with the patch I just filed, I wonder if we actually want to keep things as-is. We can link apipie docs from the new documentation and start adding Katello ones there as well. Or we can simply move things into the new repo under the new directory structure and keep the old ones alive for few years until versions are too old so we can simply remove them from there.

What you guys prefer. I lean towards:

  • Cleaning the theforeman.org github repo, keeping the files there for a while.
  • Creating the new repo and subdomain only for API docs, start adding more plugins there.
  • Linking the new subdomain from both old and new docs.

I’d like to move them out of our current repo. So not just drop files as you did now but 100% move them. If needed, we can create redirects - I’m sure we can write some Apache rewrite rule. This helps search engines to find the new content. So:

  • Create apidoc.theforeman.org (or similar, let the bikeshedding commence)
  • Fill the new site with all docs, including all the way back to 1.1 since that’s what the current website has
  • Build redirects
  • Remove old content
1 Like

Agreed, except we already deleted many verisons including 1.1, these directories are just stubs now. But I can dig this in the git history if needed. Do we REALLY want to go 10+ years back tho? :slight_smile:

Ah, I didn’t actually click the links. What I meant was basically to move all files from one repo to the other without changing them.

The repo is ready:

Unfortunately, I do not see any content under:

http://apidocs.github.io/foreman/2.4/v2.html

I already configured the CNAME file so pehraps GH does not server it under their vhost. I am not sure.

Can someone create the CNAME in our DNS please?

And here is a PR for rewrite rules once we move the content:

https://github.com/theforeman/foreman-infra/pull/1600

the correct URL would be theforeman.github.io/apidocs/…, but that redirects to apidocs.tfm.o which doesn’t exist yet. I’ll create the DNS entry (done).

in the meantime, can we please first decide how we want to build this, before rushing things?

I’d prefer if the new repo wouldn’t need any build step during deployment and just have all the HTML committed (the most part is static HTML anyways).
If we just move the current apidocs over, we’ll get no indexes (and I am not actually sure GH generates directory indexes in this case – I think not).
If we’ll have an automated way to add new docs (Jenkins job or similar), the same job could go and generate an index page and commit it to the repo. That’s how we build the version index for theforeman.github.io/foreman-ansible-modules/ and so far noone complained :wink:

1 Like

Yeah, this deserves a summary email:

  • I am moving /api directory away from theforeman.org repo to the newly created repo. DONE
  • I am cleaning the current content (drop all translations, remove links to translations). DONE
  • I am dropping all markdown/jekyll stuff, the new repo will only contain HTML pages with no indexes (we can simply link the proper documents from our site and users can use back button to return back). DONE
  • API docs will be in its simple form (no iframe, no Foreman icon etc). DONE
  • I am creating a “cleanup” PR in the original repo, but we might actually want to drop the content completely from there instead merging it. I just had a script that also works on the old content and I wanted to see how much space can be saved for comparsion. DONE
  • I am creating an infra PR witch http server redirects from old URL to the new subdomain. DONE
  • The plan is to stick with the current API generation process (manually copying files into the new github repo), unless someone else wants to step in and automatize this.
  • Plugin authors are welcome to start adding API documentation into the new github repo (just wait until it is published and online).

It is a bit fast, but I left “do not merge” comments on those PRs. Since I was on it I thought I would prepare everything in advance.

Not done, but an open PR:
https://github.com/theforeman/theforeman.org/pull/1807

I meant doing this in the new github repo, that’s been done already. The new content is clean of all translations.

Ok the new subdomain is active, at least in my DNS path:

http://apidocs.theforeman.org/foreman/2.4/v2.html

I think it will be better instead of keeping copies in the original repo to delete everything and install those rewrite rules instead, what you think? Alternatively I can drop index.html files with a redirect to the original place too. That could be easier because the path will actually change:

https://theforeman.org/api/2.4/index.html

For these cases I can actually drop index.html into the directories on the new subdomain with a redirect so httpd rewrite would work.

Looks like the links in it are broken though, they replace the version number with apidoc. Perhaps it should be placed in e.g http://apidocs.theforeman.org/foreman/2.4/apidoc/v2.html?

Yeah I moved them, I need to move it back. I will also drop those index.html files so the landing URL will be nicer, shorter and also compatible with the old path (so we can just rewrite those URLs).

Ok now it works. There is now a redirect page:

http://apidocs.theforeman.org/foreman/2.4/

will get you to:

http://apidocs.theforeman.org/foreman/2.4/apidoc/v2.html

This means we can rewrite links on our old page:

https://theforeman.org/api/2.4/index.html -> https://apidocs.theforeman.org/foreman/2.4/index.html

Unless I am missing anything, we can:

  • Review and merge the rewrite rules
  • Remove all /api content from our theforeman.org repository (saving 700 MB of space there)

Correction: I enabled HTTPS and also created “latest” symlink so everything should work.