search

asciidoctor / asciidoctor.org

:globe_with_meridians: Asciidoctor project site. Composed in AsciiDoc. Baked with Awestruct.
https://asciidoctor.org
Other
322 stars 807 forks source link

Self-host Ruby API documentation #1011

Open danyill opened 2 years ago

danyill commented 2 years ago

The API documentation for Ruby is available on Rubydoc and is linked from the Asciidoctor documentation:

https://docs.asciidoctor.org/asciidoctor/latest/api/

It's back up today (hurrah!) but is very regularly down at URLs like:

https://www.rubydoc.info/gems/asciidoctor/2.0.16

Sometimes a previous version can be found by modifying the URL.

IMHO we need better uptime and this should not be excessively onerous or complex in 2021 for a static website. I recommend we generate the documentation ourselves using Yard (which is what Rubydoc uses) in CI and then bundle it into docs.asciidoctor.org to take advantage of the resiliency/redundancy of Netlify.

mojavelinux commented 2 years ago

Looking forward, I'd really like to bring all the APIs for Asciidoctor under one "roof". Therefore, I'm open to setting up the domain api.asciidoctor.org for this purpose. We'd manage the site on Netlify, like we do the other sites, and it would get its own build. Then we can put any amount of API docs there.

ggrossetie commented 2 years ago

We'd manage the site on Netlify, like we do the other sites, and it would get its own build. Then we can put any amount of API docs there.

I guess we would need to create a GitHub repository api.asciidoctor.org? (In order to configure a Netlify build, right?) Since we don't want to rebuild all versions/releases all the time, I suppose we would have to commit the generated static files? We would also probably need to notify this repository when we release a new version of Asciidoctor, Asciidoctor.js or AsciidoctorJ.

The build could:

  1. checkout asciidoctor/asciidoctor, asciidoctor/asciidoctor.js or asciidoctor/asciidoctorj
  2. install (dev) dependencies
  3. generate the documentation: yard, npm run docs --prefix packages/core or ./gradlew javadoc
  4. copy generated files to a common directory structure:
api.asciidoctor.org/asciidoctor/latest
api.asciidoctor.org/asciidoctorj/latest
api.asciidoctor.org/asciidoctor.js/latest
api.asciidoctor.org/asciidoctor/2.0.16
api.asciidoctor.org/asciidoctorj/2.5.2
api.asciidoctor.org/asciidoctor.js/2.2.5
  1. commit files and push
  2. (it triggers Netlify build)
  3. Netlify deploy static files to api.asciidoctor.org

@mojavelinux is that what you have in mind?