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

[Carbone, Maura]

Hello all,

I successfully build the docs today (on my mac) and I made a few little changes to Dave’s thing based on my experiences.

One time:

1. Set up ArchivesSpace for development

  1.  Clone repository
git clone https://github.com/archivesspace/archivesspace.git<https://nam05.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Farchivesspace%2Farchivesspace.git&data=02%7C01%7Cmaura.carbone%40yale.edu%7Cd5da1a12d84440df159408d75d45bd16%7Cdd8cbebb21394df8b4114e3e87abeb5c%7C0%7C0%7C637080426435313725&sdata=OMLHzUl9dPV3sQ%2BtOhXldfaq%2FIRiiC8ZOR16PlneQtQ%3D&reserved=0>
  2.  Run following install tasks
build/run bootstrap
build/run db:migrate
2. Set up a working “system ruby”, we will install the correct bundler in the next step
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


If you encounter the following error:
[java] Cloning into './tech_docs'...
     [java] Warning: Permanently added the RSA host key for IP address '140.82.114.4' to the list of known hosts.
     [java] git at github.com<mailto:git at github.com>: Permission denied (publickey).
     [java] fatal: Could not read from remote repository.
you will need to edit the pull_tech_docs.rb file, found in the scripts directory. In your editor of choice, change the line ‘git_url = “git at github.com:archivesspace/tech-docs.git<mailto:git at github.com:archivesspace/tech-docs.git>”’ to ‘git_url = https://github.com/archivesspace/tech-docs.git’. Save and then retry build/run doc:build (I am putting in a PR for this change in global since I have heard others encounter this problem)
2. Run the slate build process to generate the final HTML
                cd docs/slate/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.


From: <archivesspace_api_doc_adhoc-bounces at lyralists.lyrasis.org> on behalf of "Mayo, Dave" <dave_mayo at harvard.edu>
Reply-To: ArchivesSpace API Ad Hoc Working Group <archivesspace_api_doc_adhoc at lyralists.lyrasis.org>
Date: Wednesday, October 30, 2019 at 10:30 AM
To: "archivesspace_api_doc_adhoc at lyralists.lyrasis.org" <archivesspace_api_doc_adhoc at lyralists.lyrasis.org>
Subject: Re: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist

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<https://nam05.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Farchivesspace%2Farchivesspace.git&data=02%7C01%7Cmaura.carbone%40yale.edu%7Cd5da1a12d84440df159408d75d45bd16%7Cdd8cbebb21394df8b4114e3e87abeb5c%7C0%7C0%7C637080426435313725&sdata=OMLHzUl9dPV3sQ%2BtOhXldfaq%2FIRiiC8ZOR16PlneQtQ%3D&reserved=0>
  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/20191031/c80870ec/attachment-0001.html>