[Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist

Mayo, Dave dave_mayo at harvard.edu
Wed Oct 30 10:30:36 EDT 2019


Note: as has been pointed out to me, on the line starting 2. Set up a working “system ruby”, the gem install bit there looks like a command line to run – IT IS NOT, I was writing out pseudocode without thinking.

The correct bundler command is the one below in bullet point 3,

gem install bundler –version ‘< 2.0’
--
Dave Mayo (he/him)
Senior Digital Library Software Engineer
Harvard University > HUIT > LTS

From: "Mayo, Dave" <dave_mayo at harvard.edu>
Date: Tuesday, October 29, 2019 at 3:07 PM
To: "archivesspace_api_doc_adhoc at lyralists.lyrasis.org" <archivesspace_api_doc_adhoc at lyralists.lyrasis.org>
Subject: Concise "how to build ASpace API Docs" checklist

So, the full docs are here: https://archivesspace.github.io/archivesspace/user/building-an-archivesspace-release/
Docs for the build system: https://archivesspace.github.io/archivesspace/user/archivesspace-build-system/
I’m going to split this into “one-time” and “every time” sections:
This all assumes that “archivesspace” is the root directory of the github checkout, if there’s a cd command, it is relative to this directory
One time:

1. Set up ArchivesSpace for development

  1.  Clone repository
git clone https://github.com/archivesspace/archivesspace.git
  2.  Run following install tasks
build/run bootstrap
build/run db:migrate
2. Set up a working “system ruby” and gem install bundler “<2.0” I’m not going to go into detail here, but you need to be able to run `bundle install` from a command line
3. Set up the slate build environment:
                cd docs/slate
                gem install bundler --version '< 2.0'
                bundle install –binstubs
4. Generate examples JSON:
                build/run backend:test -Dspec='documentation_spec.rb'
Every Time:

1. Generate the docs (this takes the changes from Endpoints and puts them in the Slate markdown file)
                build/run doc:build
2. Run the slate build process to generate the final HTML
                cd docs/build
                ./bin/middleman build # this builds the docs into docs/slate/build
               ./bin/middleman server # if you want to look at them on localhost:4567
3. To actually change the docs (i.e. to prepare them for submitting in a pull request):
              rm -r docs/api
                mv docs/slate/build docs/api
4. Adding them to git looks like:
                git add docs/api docs/slate/source/index.md
               git add <whichever files have the endpoints you changed>
               git commit -m’<message describing docs update>’

The following steps (7+ in the “how to build a release”) will be handled by project team or whomever merges these changes, I think. Making pull requests will be left till next meeting.

I hope this is helpful, let me know if I missed anything or anything is unclear/insufficiently covered.

- Dave Mayo

--
Dave Mayo (he/him)
Senior Digital Library Software Engineer
Harvard University > HUIT > LTS
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lyralists.lyrasis.org/pipermail/archivesspace_api_doc_adhoc/attachments/20191030/4c5c8e9c/attachment-0001.html>


More information about the Archivesspace_api_doc_adhoc mailing list