Uploaded image for project: 'Ruby Driver'
  1. Ruby Driver
  2. RUBY-3209

Include API doc generation in driver/ODM release scripts

    • Type: Icon: Task Task
    • Resolution: Done
    • Priority: Icon: Minor - P4 Minor - P4
    • None
    • Affects Version/s: None
    • Component/s: Docs
    • None

      As part of the migration of the Ruby driver and mongoid docs from the legacy toolchain to the new one, we will be using a new standardized Makefile that the Docs Platform team manages for those builds. The existing Ruby docs Makefile includes a target to generate the API docs from the Ruby driver project using yard.

      As part of the migration, we proposed that API doc generation become part of the Ruby driver and mongoid release processes in Slack. This was deemed acceptable. For posterity, this makes sense to us since y'all are far more familiar with the doc generation tooling and when a new release/update is needed. The non-generated content is likely to be updated more often than the generated, and at a different cadence, so it makes sense to include the API doc update as part of the driver/ODM release rather than baking it into the hand-written content releases. This has the added benefit for the Docs Platform of not needing to add more programming language installations to our already rather length Docker image build, which we appreciate 🙂.

      MongoDB's docs are served out of S3 buckets and CDN'd via the corporate Cloudfront CDN. We have created a user with the necessary permissions to write to docs/ruby* and docs/mongoid* in production and docs-qa/ruby* and docs-qa/mongoid* in preproduction, as well as whatever path desired in the staging environment. You do not need to use preproduction or staging unless you want to, though the preprod environment is likely to be useful to ensure your upload script is working as expected. I'll send the credentials via an 0bin on Slack.

      The following table should provide the necessary bucket, path info to set things up.

        bucket file path prefix to which to write
      production docs-mongodb-org-dotcomprd docs/ruby-driver/VERSION/api/
      docs/mongoid/VERSION/api/
      preproduction docs-mongodb-org-dotcomstg
       
      docs-qa/ruby-driver/VERSION/api/
      docs-qa/mongoid/VERSION/api/
       
      staging docs-mongodb-org-prd-staging ruby-driver/WHATEVER
      mongoid/WHATEVER

      Terminology notes:

      • production == production
      • preproduction == our tooling test environment, mirrors production but is usually a tooling release 'ahead'
      • staging == informal place you can stage changes for preview / review

            Assignee:
            dmitry.rybakov@mongodb.com Dmitry Rybakov
            Reporter:
            allison.moore@mongodb.com Allison Reinheimer Moore (Inactive)
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Created:
              Updated:
              Resolved: