[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