search

commercetools / commercetools-docs-kit

Tools and components for developing Documentation websites 🛠
https://docs-kit.commercetools.vercel.app
MIT License
18 stars 5 forks source link

Automate RAML specs generation #229

Closed davifantasia closed 4 years ago

davifantasia commented 4 years ago

Current Process

  1. User sets up a Gatsby website which based on the theme @commercetools-docs/gatsby-theme-api-docs. See more information on Gatsby theme on their website here.
  2. User clones RMF Codegen repo
  3. User runs ./gradlew shadow to generate jar file.
  4. User needs to understand location of jar file so the next command can work (I just copy over the file to wherever I want to run the next command)
  5. User runs another command to generate RAML files as follows 
    rmf-codegen % time ./rmf-gen.sh generate -o <gatsby-theme-api-specs-path> -t ramldoc <raml-api-path>
  6. Startup Gatsby site

Problem

Given that the bulk of intended users don't have software development background, the process can get easily complicated and therefore confusing. Setting up the actual doc site already has several steps.

Proposed Automated Process

  1. Setup actual site
  2. Provide path to RAML specs directory that is to be generated
  3. Startup Gatsby site

Possible Development Steps to Automation

  1. Standard requirement for some sort of config file that will contain the path of the RAML api to be generated.
  2. Pre-build process
    • Jar file is downloaded (needs to be published somewhere)
    • Script that runs jar file is called with path from step 1 passed to it.
    • RAML files are generated in api-specs directory.
  3. After build is complete generated RAML files should be available i the application.
emmenko commented 4 years ago

Thanks for looking into that.

I have a question first: do we expect "generating the raml specs" to be done by developers or by writers? From what I understand, it's something that developers would do.

So what you're proposing is to have a single script that ties all the things together? Or did I misunderstood something?

davifantasia commented 4 years ago

I have a question first: do we expect "generating the raml specs" to be done by developers or by writers? From what I understand, it's something that developers would do.

Developers should be responsible for that yes, but I'm working with the presumption that anyone who is not a developer should be able to set up a website for documentation using gatsby-theme-api-docs.

davifantasia commented 4 years ago

So what you're proposing is to have a single script that ties all the things together? Or did I misunderstood something?

That is correct.

emmenko commented 4 years ago

I'm working with the presumption that anyone who is not a developer should be able to set up a website for documentation using gatsby-theme-api-docs

Is this what we want to achieve?

davifantasia commented 4 years ago

Is this what we want to achieve?

I believe so.

davifantasia commented 4 years ago

I have a question first: do we expect "generating the raml specs" to be done by developers or by writers? From what I understand, it's something that developers would do.

Developers should be responsible for that yes, but I'm working with the presumption that anyone who is not a developer should be able to set up a website for documentation using gatsby-theme-api-docs.

@nkuehn is this correct?

nkuehn commented 4 years ago

Hi, a few clarifications:

Does that help?

My idea of a "rollout" to make it easier to use:

  1. Phase 1: manual local installation or build of the rmfgen JAR into the local path, a shell script to call it with the correct source and destination folder paths.
  2. Phase 2: the rmfgen JAR is published e.g. on github or mavencentral and we have a wrapper npm package that downloads it and provides the binary path to npm/yarn (analogous to how we handle the vale linter). Java still needs to be installed manually.
  3. Phase 3: rocket science is able to generate a native binary so the user does not need java any more :-)
emmenko commented 4 years ago

How about we use a github action or something to do the work? That way, nobody has to install anything, we just need to "trigger" the action to run, which will then create a PR with the changes.

The trigger can be different things, and is up to us to find a good one. Some examples:

nkuehn commented 4 years ago

CI doesn't solve the use case at all unfortunately because RAML changes are a part of the writing "flow" and you need relatively direct feedback in the resulting site. E.g. you want to move a piece of description from a RAML field description to the general text or vice versa. Or you put some nontrivial markdown into a RAML description and need feedback whether it works and looks the way you want.

Via CI the feedback cycle is way too long. In fact, even having to call the converter script now is an ugly regression from the live preview when authoring RAML that we had when we used the old JS parser. Mid-term I rather want to get back to a mode the dynamically listens to RAML changes and updates the dev mode site live than to further decouple it by switching to CI.

emmenko commented 4 years ago

An alternative is to bundle the script in a docker container, so people only need to have Docker installed.

I'm just trying to find a way to avoid people having to install "unnecessary" tools.

nkuehn commented 4 years ago

It's the key tool for the API spec documentation work and hence pretty "necessary". Software does not become "unnecessary" by not being preinstalled on an Apple product and/or being my favorite tech stack.

We tried pushing docker in the existing website stack and it turned out to be much harder to use and and understand than installing ruby via homebrew and simply running the generator. If you don't run docker anyways for your work having it in the background is a horribly resource hog and the daemon takes ages to start up. Most users went back to running it locally.