From dave_mayo at harvard.edu  Tue Oct 29 15:07:38 2019
From: dave_mayo at harvard.edu (Mayo, Dave)
Date: Tue, 29 Oct 2019 19:07:38 +0000
Subject: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API
	Docs" checklist
Message-ID: <0C6EDFCF-A1E4-4508-8011-148E905F64F0@harvard.edu>

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/20191029/28777150/attachment.html>

From dave_mayo at harvard.edu  Wed Oct 30 10:30:36 2019
From: dave_mayo at harvard.edu (Mayo, Dave)
Date: Wed, 30 Oct 2019 14:30:36 +0000
Subject: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API
	Docs" checklist
In-Reply-To: <0C6EDFCF-A1E4-4508-8011-148E905F64F0@harvard.edu>
References: <0C6EDFCF-A1E4-4508-8011-148E905F64F0@harvard.edu>
Message-ID: <5FB46097-F078-4A44-8C27-24667AEA37D5@harvard.edu>

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>

From maura.carbone at yale.edu  Thu Oct 31 09:16:45 2019
From: maura.carbone at yale.edu (Carbone, Maura)
Date: Thu, 31 Oct 2019 13:16:45 +0000
Subject: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API
 Docs" checklist
In-Reply-To: <5FB46097-F078-4A44-8C27-24667AEA37D5@harvard.edu>
References: <0C6EDFCF-A1E4-4508-8011-148E905F64F0@harvard.edu>
 <5FB46097-F078-4A44-8C27-24667AEA37D5@harvard.edu>
Message-ID: <171B0B65-0EF7-4A43-942F-58F8C88B808E@yale.edu>

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>