[Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist
dave_mayo at harvard.edu
Tue Oct 29 15:07:38 EDT 2019
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
1. Set up ArchivesSpace for development
1. Clone repository
git clone https://github.com/archivesspace/archivesspace.git
2. Run following install tasks
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:
gem install bundler --version '< 2.0'
bundle install –binstubs
4. Generate examples JSON:
build/run backend:test -Dspec='documentation_spec.rb'
1. Generate the docs (this takes the changes from Endpoints and puts them in the Slate markdown file)
2. Run the slate build process to generate the final HTML
./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...
More information about the Archivesspace_api_doc_adhoc