From Rachel.Donahue at usda.gov Mon Nov 4 10:07:19 2019 From: Rachel.Donahue at usda.gov (Donahue, Rachel - ARS) Date: Mon, 4 Nov 2019 15:07:19 +0000 Subject: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist In-Reply-To: <171B0B65-0EF7-4A43-942F-58F8C88B808E@yale.edu> References: <0C6EDFCF-A1E4-4508-8011-148E905F64F0@harvard.edu> <5FB46097-F078-4A44-8C27-24667AEA37D5@harvard.edu> <171B0B65-0EF7-4A43-942F-58F8C88B808E@yale.edu> Message-ID: Hi all, I tried building ASpace last night from master and kept running into a problem with the sassc gem?not sure why, it would install as a regular gem just fine. This morning I was able to build from the v2.6.0 tag, but running build/run backend:test -Dspec='documentation_spec.rb' results in ?0 examples, 0 failures? which then of course makes doc:build fail due to the lack of an examples file. Any ideas on how to fix this? I did run the full backend:test before trying just the documentation specfile. Alternately, perhaps one of you has a 2.6.0 build and could just share your endpoint_examples.json file? --Rachel From: archivesspace_api_doc_adhoc-bounces at lyralists.lyrasis.org On Behalf Of Carbone, Maura Sent: Thursday, October 31, 2019 9:17 AM To: ArchivesSpace API Ad Hoc Working Group Subject: Re: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist 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 a. Clone repository git clone https://github.com/archivesspace/archivesspace.git b. 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: 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?? 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 git commit -m?? 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: > on behalf of "Mayo, Dave" > Reply-To: ArchivesSpace API Ad Hoc Working Group > Date: Wednesday, October 30, 2019 at 10:30 AM To: "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" > Date: Tuesday, October 29, 2019 at 3:07 PM To: "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 a. Clone repository git clone https://github.com/archivesspace/archivesspace.git b. 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 git commit -m?? 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 This electronic message contains information generated by the USDA solely for the intended recipients. Any unauthorized interception of this message or the use or disclosure of the information it contains may violate the law and subject the violator to civil or criminal penalties. If you believe you have received this message in error, please notify the sender and delete the email immediately. -------------- next part -------------- An HTML attachment was scrubbed... URL: From Rachel.Donahue at usda.gov Mon Nov 4 12:39:15 2019 From: Rachel.Donahue at usda.gov (Donahue, Rachel - ARS) Date: Mon, 4 Nov 2019 17:39:15 +0000 Subject: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist In-Reply-To: References: <0C6EDFCF-A1E4-4508-8011-148E905F64F0@harvard.edu> <5FB46097-F078-4A44-8C27-24667AEA37D5@harvard.edu> <171B0B65-0EF7-4A43-942F-58F8C88B808E@yale.edu> Message-ID: An update from Windows land: Maura sent me the two examples files and I installed Node.js?after that, everything worked fine (for 2.6.0, error for building from master attached). I ran all the commands from git bash, which is packaged with this git installer: https://git-scm.com/download/win I also always install Ruby with the RubyInstaller, because it?s easy and includes tools to help make Windows behave: https://rubyinstaller.org/downloads/ Make sure you say yes to installing the MSYS2 toolchain. I?m currently running Ruby 2.6.5-1 --Rachel From: Donahue, Rachel - ARS Sent: Monday, November 4, 2019 10:07 AM To: ArchivesSpace API Ad Hoc Working Group Subject: RE: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist Hi all, I tried building ASpace last night from master and kept running into a problem with the sassc gem?not sure why, it would install as a regular gem just fine. This morning I was able to build from the v2.6.0 tag, but running build/run backend:test -Dspec='documentation_spec.rb' results in ?0 examples, 0 failures? which then of course makes doc:build fail due to the lack of an examples file. Any ideas on how to fix this? I did run the full backend:test before trying just the documentation specfile. Alternately, perhaps one of you has a 2.6.0 build and could just share your endpoint_examples.json file? --Rachel From: archivesspace_api_doc_adhoc-bounces at lyralists.lyrasis.org On Behalf Of Carbone, Maura Sent: Thursday, October 31, 2019 9:17 AM To: ArchivesSpace API Ad Hoc Working Group Subject: Re: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist 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 a. Clone repository git clone https://github.com/archivesspace/archivesspace.git b. 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: 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?? 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 git commit -m?? 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: > on behalf of "Mayo, Dave" > Reply-To: ArchivesSpace API Ad Hoc Working Group > Date: Wednesday, October 30, 2019 at 10:30 AM To: "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" > Date: Tuesday, October 29, 2019 at 3:07 PM To: "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 a. Clone repository git clone https://github.com/archivesspace/archivesspace.git b. 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 git commit -m?? 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 This electronic message contains information generated by the USDA solely for the intended recipients. Any unauthorized interception of this message or the use or disclosure of the information it contains may violate the law and subject the violator to civil or criminal penalties. If you believe you have received this message in error, please notify the sender and delete the email immediately. -------------- next part -------------- An HTML attachment was scrubbed... URL: -------------- next part -------------- An embedded and charset-unspecified text was scrubbed... Name: aspace_sassc_error.txt URL: From dave_mayo at harvard.edu Thu Nov 7 10:24:26 2019 From: dave_mayo at harvard.edu (Mayo, Dave) Date: Thu, 7 Nov 2019 15:24:26 +0000 Subject: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist In-Reply-To: References: <0C6EDFCF-A1E4-4508-8011-148E905F64F0@harvard.edu> <5FB46097-F078-4A44-8C27-24667AEA37D5@harvard.edu> <171B0B65-0EF7-4A43-942F-58F8C88B808E@yale.edu> Message-ID: <15A5B412-EA72-4380-BA04-3BA38A09C886@harvard.edu> Nice job! I?ve been flailing at getting a Windows build env for A While, I?m excited that we have at least an example of something that works! My guess for the issue with building on master is old versions of headers/etc in your MSYS2 distribution? It looks like it?s failing bc it can?t find some c99 header stuff; depending on when you got Rubyinstaller and what version of MSYS2, it might be before they had support for c99? -- Dave Mayo (he/him) Senior Digital Library Software Engineer Harvard University > HUIT > LTS From: on behalf of "Donahue, Rachel - ARS" Reply-To: ArchivesSpace API Ad Hoc Working Group Date: Monday, November 4, 2019 at 12:39 PM To: ArchivesSpace API Ad Hoc Working Group Subject: Re: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist An update from Windows land: Maura sent me the two examples files and I installed Node.js?after that, everything worked fine (for 2.6.0, error for building from master attached). I ran all the commands from git bash, which is packaged with this git installer: https://git-scm.com/download/win I also always install Ruby with the RubyInstaller, because it?s easy and includes tools to help make Windows behave: https://rubyinstaller.org/downloads/ Make sure you say yes to installing the MSYS2 toolchain. I?m currently running Ruby 2.6.5-1 --Rachel From: Donahue, Rachel - ARS Sent: Monday, November 4, 2019 10:07 AM To: ArchivesSpace API Ad Hoc Working Group Subject: RE: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist Hi all, I tried building ASpace last night from master and kept running into a problem with the sassc gem?not sure why, it would install as a regular gem just fine. This morning I was able to build from the v2.6.0 tag, but running build/run backend:test -Dspec='documentation_spec.rb' results in ?0 examples, 0 failures? which then of course makes doc:build fail due to the lack of an examples file. Any ideas on how to fix this? I did run the full backend:test before trying just the documentation specfile. Alternately, perhaps one of you has a 2.6.0 build and could just share your endpoint_examples.json file? --Rachel From: archivesspace_api_doc_adhoc-bounces at lyralists.lyrasis.org On Behalf Of Carbone, Maura Sent: Thursday, October 31, 2019 9:17 AM To: ArchivesSpace API Ad Hoc Working Group Subject: Re: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist 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 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: 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?? 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 git commit -m?? 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: > on behalf of "Mayo, Dave" > Reply-To: ArchivesSpace API Ad Hoc Working Group > Date: Wednesday, October 30, 2019 at 10:30 AM To: "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" > Date: Tuesday, October 29, 2019 at 3:07 PM To: "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 git commit -m?? 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 This electronic message contains information generated by the USDA solely for the intended recipients. Any unauthorized interception of this message or the use or disclosure of the information it contains may violate the law and subject the violator to civil or criminal penalties. If you believe you have received this message in error, please notify the sender and delete the email immediately. -------------- next part -------------- An HTML attachment was scrubbed... URL: From Rachel.Donahue at usda.gov Thu Nov 7 10:55:32 2019 From: Rachel.Donahue at usda.gov (Donahue, Rachel - ARS) Date: Thu, 7 Nov 2019 15:55:32 +0000 Subject: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist In-Reply-To: <15A5B412-EA72-4380-BA04-3BA38A09C886@harvard.edu> References: <0C6EDFCF-A1E4-4508-8011-148E905F64F0@harvard.edu> <5FB46097-F078-4A44-8C27-24667AEA37D5@harvard.edu> <171B0B65-0EF7-4A43-942F-58F8C88B808E@yale.edu> <15A5B412-EA72-4380-BA04-3BA38A09C886@harvard.edu> Message-ID: I installed Ruby last week and it came out on 10/1 of this year. ?\_(?)_/? 2.7.0 also builds fine--is the c99 stuff new post-release? --Rachel From: archivesspace_api_doc_adhoc-bounces at lyralists.lyrasis.org On Behalf Of Mayo, Dave Sent: Thursday, November 7, 2019 10:24 AM To: ArchivesSpace API Ad Hoc Working Group Subject: Re: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist Nice job! I?ve been flailing at getting a Windows build env for A While, I?m excited that we have at least an example of something that works! My guess for the issue with building on master is old versions of headers/etc in your MSYS2 distribution? It looks like it?s failing bc it can?t find some c99 header stuff; depending on when you got Rubyinstaller and what version of MSYS2, it might be before they had support for c99? -- Dave Mayo (he/him) Senior Digital Library Software Engineer Harvard University > HUIT > LTS From: > on behalf of "Donahue, Rachel - ARS" > Reply-To: ArchivesSpace API Ad Hoc Working Group > Date: Monday, November 4, 2019 at 12:39 PM To: ArchivesSpace API Ad Hoc Working Group > Subject: Re: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist An update from Windows land: Maura sent me the two examples files and I installed Node.js?after that, everything worked fine (for 2.6.0, error for building from master attached). I ran all the commands from git bash, which is packaged with this git installer: https://git-scm.com/download/win I also always install Ruby with the RubyInstaller, because it?s easy and includes tools to help make Windows behave: https://rubyinstaller.org/downloads/ Make sure you say yes to installing the MSYS2 toolchain. I?m currently running Ruby 2.6.5-1 --Rachel From: Donahue, Rachel - ARS Sent: Monday, November 4, 2019 10:07 AM To: ArchivesSpace API Ad Hoc Working Group > Subject: RE: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist Hi all, I tried building ASpace last night from master and kept running into a problem with the sassc gem?not sure why, it would install as a regular gem just fine. This morning I was able to build from the v2.6.0 tag, but running build/run backend:test -Dspec='documentation_spec.rb' results in ?0 examples, 0 failures? which then of course makes doc:build fail due to the lack of an examples file. Any ideas on how to fix this? I did run the full backend:test before trying just the documentation specfile. Alternately, perhaps one of you has a 2.6.0 build and could just share your endpoint_examples.json file? --Rachel From: archivesspace_api_doc_adhoc-bounces at lyralists.lyrasis.org > On Behalf Of Carbone, Maura Sent: Thursday, October 31, 2019 9:17 AM To: ArchivesSpace API Ad Hoc Working Group > Subject: Re: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist 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 a. Clone repository git clone https://github.com/archivesspace/archivesspace.git b. 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: 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?? 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 git commit -m?? 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: > on behalf of "Mayo, Dave" > Reply-To: ArchivesSpace API Ad Hoc Working Group > Date: Wednesday, October 30, 2019 at 10:30 AM To: "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" > Date: Tuesday, October 29, 2019 at 3:07 PM To: "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 a. Clone repository git clone https://github.com/archivesspace/archivesspace.git b. 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 git commit -m?? 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 This electronic message contains information generated by the USDA solely for the intended recipients. Any unauthorized interception of this message or the use or disclosure of the information it contains may violate the law and subject the violator to civil or criminal penalties. If you believe you have received this message in error, please notify the sender and delete the email immediately. -------------- next part -------------- An HTML attachment was scrubbed... URL: From dave_mayo at harvard.edu Tue Nov 12 10:28:09 2019 From: dave_mayo at harvard.edu (Mayo, Dave) Date: Tue, 12 Nov 2019 15:28:09 +0000 Subject: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist In-Reply-To: References: <0C6EDFCF-A1E4-4508-8011-148E905F64F0@harvard.edu> <5FB46097-F078-4A44-8C27-24667AEA37D5@harvard.edu> <171B0B65-0EF7-4A43-942F-58F8C88B808E@yale.edu> <15A5B412-EA72-4380-BA04-3BA38A09C886@harvard.edu> Message-ID: The c99 stuff is afaict related to building the C library version of SASS which is swapped in for the deprecated Ruby-based SASS processor stuff post 2.7.0. -- Dave Mayo (he/him) Senior Digital Library Software Engineer Harvard University > HUIT > LTS From: on behalf of "Donahue, Rachel - ARS" Reply-To: ArchivesSpace API Ad Hoc Working Group Date: Thursday, November 7, 2019 at 10:55 AM To: ArchivesSpace API Ad Hoc Working Group Subject: Re: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist I installed Ruby last week and it came out on 10/1 of this year. ?\_(?)_/? 2.7.0 also builds fine--is the c99 stuff new post-release? --Rachel From: archivesspace_api_doc_adhoc-bounces at lyralists.lyrasis.org On Behalf Of Mayo, Dave Sent: Thursday, November 7, 2019 10:24 AM To: ArchivesSpace API Ad Hoc Working Group Subject: Re: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist Nice job! I?ve been flailing at getting a Windows build env for A While, I?m excited that we have at least an example of something that works! My guess for the issue with building on master is old versions of headers/etc in your MSYS2 distribution? It looks like it?s failing bc it can?t find some c99 header stuff; depending on when you got Rubyinstaller and what version of MSYS2, it might be before they had support for c99? -- Dave Mayo (he/him) Senior Digital Library Software Engineer Harvard University > HUIT > LTS From: > on behalf of "Donahue, Rachel - ARS" > Reply-To: ArchivesSpace API Ad Hoc Working Group > Date: Monday, November 4, 2019 at 12:39 PM To: ArchivesSpace API Ad Hoc Working Group > Subject: Re: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist An update from Windows land: Maura sent me the two examples files and I installed Node.js?after that, everything worked fine (for 2.6.0, error for building from master attached). I ran all the commands from git bash, which is packaged with this git installer: https://git-scm.com/download/win I also always install Ruby with the RubyInstaller, because it?s easy and includes tools to help make Windows behave: https://rubyinstaller.org/downloads/ Make sure you say yes to installing the MSYS2 toolchain. I?m currently running Ruby 2.6.5-1 --Rachel From: Donahue, Rachel - ARS Sent: Monday, November 4, 2019 10:07 AM To: ArchivesSpace API Ad Hoc Working Group > Subject: RE: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist Hi all, I tried building ASpace last night from master and kept running into a problem with the sassc gem?not sure why, it would install as a regular gem just fine. This morning I was able to build from the v2.6.0 tag, but running build/run backend:test -Dspec='documentation_spec.rb' results in ?0 examples, 0 failures? which then of course makes doc:build fail due to the lack of an examples file. Any ideas on how to fix this? I did run the full backend:test before trying just the documentation specfile. Alternately, perhaps one of you has a 2.6.0 build and could just share your endpoint_examples.json file? --Rachel From: archivesspace_api_doc_adhoc-bounces at lyralists.lyrasis.org > On Behalf Of Carbone, Maura Sent: Thursday, October 31, 2019 9:17 AM To: ArchivesSpace API Ad Hoc Working Group > Subject: Re: [Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist 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 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: 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?? 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 git commit -m?? 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: > on behalf of "Mayo, Dave" > Reply-To: ArchivesSpace API Ad Hoc Working Group > Date: Wednesday, October 30, 2019 at 10:30 AM To: "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" > Date: Tuesday, October 29, 2019 at 3:07 PM To: "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 git commit -m?? 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 This electronic message contains information generated by the USDA solely for the intended recipients. Any unauthorized interception of this message or the use or disclosure of the information it contains may violate the law and subject the violator to civil or criminal penalties. If you believe you have received this message in error, please notify the sender and delete the email immediately. -------------- next part -------------- An HTML attachment was scrubbed... URL: