Couple of questions:
latest symlink?index.html that is now in every folder?I still think we’re rushing things here instead of thinking.
Oh, and you’re not saving a single byte from the old repo, as the files are still in the git history.
It’s saved from the deployed version, but not the source.
The usual way, I explicitly wrote I do not want to change the process but the place where we host the files.
Manually. That’s the best thing I could figure out. Alternatively we can rewrite the URL in our main menu and use the jekyll variable - I don’t think it can be used in _config.yml directly.
Manually. Just like we were copying CSS/JS files before the change. I will go ahead and describe the process in the README.
Well, these are your words. We have a new repository can be deleted from github with a single click. And three PRs which can be all closed. I like to do small things rather than talk - this is not a deal breaker.
I do for git checkouts, I assume everyone understands how git works and that the history is sealed (unless you rebase stuff and delete history). That was not the point.
Oh, by the way, the jekyll site now generates in 10 seconds instead of 50.
For the record, I added instructions into the README and provided a link from the original place.
Note that if we keep plugins API docs separately, there’s no place to see plugin extensions to core API (e.g. when host API is enriched with new fields). I wonder if there’s a way to also have a version that includes all plugins documentation. Just to be clear, that shouldn’t block any ongoing effort here, I think it’s a good change overall.
Yes, the main motivation for this effort was actually Katello, folks were asking where to put apidocs for the 4.0 documentation which now was moved from the old website into ascidoc in the new repo. The plan is to create subdirectories just like @evgeni recommended.
We can take a hint from our CI pipelines. We have:
We can decide that those are the 4 sets that we generate complete docs for.
I think the apipie output of a plugin includes the extended controllers from core, but I’ll double check.
I would (personally) prefer to have an apidoc per plugin, not collections like Ewoud proposed, as it makes it hard to see what exactly comes from which plugin. This puts the plugins that depend on Katello (foreman_rh_cloud foreman_scc_manager foreman_virt_who_configure) in a weird corner, but I’d tackle them last.
I can try hacking up a Makefile/Rakefile that can build apiepie and place them into the repo based on @lzap’s docs.
Since github pages do not support directory listings, I have added a top-level index.html generated by tree command for the first two levels of directories. This should give at least a decent starting page for those who would delete the rest of the URL and for search engines to find all the pages:
From user perspective, I’d prefer to have one docs to search in. In case I want to see a complete docs for Host creation in case I have 5 plugins, I’d have to look at 5 places. It would be awesome if apipie doc also said that endpoint/attribute is added from plugin. But that’s probably not that easy, any thoughts on this @ofedoren ?
Well, I could update apipie library:
config.show_engines = true to show engine names next to resource names. This will not require any changes in plugins (only 1 line in core). This way the top level name of a controller will be used (e.g. ForemanAnsible::Resource => “Foreman Ansible”; Foreman::Resource => “Foreman” or more neutral “Core”). Note: this is only a quick suggestion, in reality this might be slightly complicated.origin method do resource descriptions and the same as an argument to api methods. This way allows to show such info if it was provided, but this might also require quite a lot of changes. Mostly we would need to add this in all plugins.Any objections from moving? I think we are all set.
One more idea, calling FOREMAN_APIPIE_LANGS=en bundle rake apipie_dsl:static generates also DSL documentation which we currently do not publish yet. It would be good idea to generate those too. Unfortunately the task does not appear to support per-plugin generation, it seems to be collection. I am not sure if apipie even supports that for API docs, @evgeni did you have a chance to take a look?
Anyway, what blocks us from getting the content moved unchanged and speeding up the site generation? There is no reason to wait for improving the process, Katello team needs to put apipie docs somewhere and this looks like a good place to start with.
Thanks
Are there any objections from deleting apidocs from the original site and speeding up our site generation?
https://github.com/theforeman/theforeman.org/pull/1808
Thanks!
This has now been merged, please report any issues found!