[Archivesspace_api_doc_adhoc] Concise "how to build ASpace API Docs" checklist
Donahue, Rachel - ARS
Rachel.Donahue at usda.gov
Thu Nov 7 10:55:32 EST 2019
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 <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 <archivesspace_api_doc_adhoc at lyralists.lyrasis.org>
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: <archivesspace_api_doc_adhoc-bounces at lyralists.lyrasis.org<mailto:archivesspace_api_doc_adhoc-bounces at lyralists.lyrasis.org>> on behalf of "Donahue, Rachel - ARS" <Rachel.Donahue at usda.gov<mailto:Rachel.Donahue at usda.gov>>
Reply-To: ArchivesSpace API Ad Hoc Working Group <archivesspace_api_doc_adhoc at lyralists.lyrasis.org<mailto:archivesspace_api_doc_adhoc at lyralists.lyrasis.org>>
Date: Monday, November 4, 2019 at 12:39 PM
To: ArchivesSpace API Ad Hoc Working Group <archivesspace_api_doc_adhoc at lyralists.lyrasis.org<mailto:archivesspace_api_doc_adhoc at lyralists.lyrasis.org>>
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<https://gcc02.safelinks.protection.outlook.com/?url=https%3A%2F%2Furldefense.proofpoint.com%2Fv2%2Furl%3Fu%3Dhttps-3A__git-2Dscm.com_download_win%26d%3DDwMGaQ%26c%3DWO-RGvefibhHBZq3fL85hQ%26r%3D_Mv1dY22K7jvT5MD7xjbvGVzRDOUMhx4WYcnPSIzYnE%26m%3DmpB5LJB3R4GMPlWyg1r41u_Z1xC6kLtspH5OfqLNILA%26s%3D6aRIPbBr97Zw6wkaPhwa-ObpihQGpCR4XzlSnwOqMrs%26e%3D&data=02%7C01%7C%7C82209bf522be415e5e1808d76396960a%7Ced5b36e701ee4ebc867ee03cfa0d4697%7C0%7C0%7C637087370721970033&sdata=fgjSUM%2FmF19ZZMHGX%2FlUCiA%2BfdxaqE6CFXtHbblNoXg%3D&reserved=0>
I also always install Ruby with the RubyInstaller, because it’s easy and includes tools to help make Windows behave: https://rubyinstaller.org/downloads/<https://gcc02.safelinks.protection.outlook.com/?url=https%3A%2F%2Furldefense.proofpoint.com%2Fv2%2Furl%3Fu%3Dhttps-3A__rubyinstaller.org_downloads_%26d%3DDwMGaQ%26c%3DWO-RGvefibhHBZq3fL85hQ%26r%3D_Mv1dY22K7jvT5MD7xjbvGVzRDOUMhx4WYcnPSIzYnE%26m%3DmpB5LJB3R4GMPlWyg1r41u_Z1xC6kLtspH5OfqLNILA%26s%3DhJg4uAOQVSX-dvi_ycJW4WfQ9s-G8Z-_L-2PTfYaIqY%26e%3D&data=02%7C01%7C%7C82209bf522be415e5e1808d76396960a%7Ced5b36e701ee4ebc867ee03cfa0d4697%7C0%7C0%7C637087370721970033&sdata=piJQkSNh33r%2BGssl1YTJ4358EKDNRMef0OGzWvfSqxo%3D&reserved=0>
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 <archivesspace_api_doc_adhoc at lyralists.lyrasis.org<mailto:archivesspace_api_doc_adhoc at lyralists.lyrasis.org>>
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<mailto:archivesspace_api_doc_adhoc-bounces at lyralists.lyrasis.org> <archivesspace_api_doc_adhoc-bounces at lyralists.lyrasis.org<mailto: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 <archivesspace_api_doc_adhoc at lyralists.lyrasis.org<mailto:archivesspace_api_doc_adhoc at lyralists.lyrasis.org>>
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<https://gcc02.safelinks.protection.outlook.com/?url=https%3A%2F%2Furldefense.proofpoint.com%2Fv2%2Furl%3Fu%3Dhttps-3A__gcc02.safelinks.protection.outlook.com_-3Furl-3Dhttps-253A-252F-252Fgithub.com-252Farchivesspace-252Farchivesspace.git-26data-3D02-257C01-257C-257Ca805c2f7824d40acabb108d75e0496de-257Ced5b36e701ee4ebc867ee03cfa0d4697-257C0-257C0-257C637081246129609892-26sdata-3DoRosRhjDQZo1Hf-252FF29idlgMuki-252FrJ8EGxkPb898A2t8-253D-26reserved-3D0%26d%3DDwMGaQ%26c%3DWO-RGvefibhHBZq3fL85hQ%26r%3D_Mv1dY22K7jvT5MD7xjbvGVzRDOUMhx4WYcnPSIzYnE%26m%3DmpB5LJB3R4GMPlWyg1r41u_Z1xC6kLtspH5OfqLNILA%26s%3DBkjVvCAfAYiUAnqUPVchtelOjwET-QFtA8Qmn8H4YKU%26e%3D&data=02%7C01%7C%7C82209bf522be415e5e1808d76396960a%7Ced5b36e701ee4ebc867ee03cfa0d4697%7C0%7C0%7C637087370721980027&sdata=U6%2FmQ9NAx6IhrsqD4710UB0n%2BH0aGWBL%2FFQdiSYEf%2FU%3D&reserved=0>
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<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<https://gcc02.safelinks.protection.outlook.com/?url=https%3A%2F%2Furldefense.proofpoint.com%2Fv2%2Furl%3Fu%3Dhttps-3A__gcc02.safelinks.protection.outlook.com_-3Furl-3Dhttps-253A-252F-252Fgithub.com-252Farchivesspace-252Ftech-2Ddocs.git-26data-3D02-257C01-257C-257Ca805c2f7824d40acabb108d75e0496de-257Ced5b36e701ee4ebc867ee03cfa0d4697-257C0-257C0-257C637081246129609892-26sdata-3DxdRFgLqFDKvu5y2bd9RQCxjTVTNgN0peJto4m98mkL8-253D-26reserved-3D0%26d%3DDwMGaQ%26c%3DWO-RGvefibhHBZq3fL85hQ%26r%3D_Mv1dY22K7jvT5MD7xjbvGVzRDOUMhx4WYcnPSIzYnE%26m%3DmpB5LJB3R4GMPlWyg1r41u_Z1xC6kLtspH5OfqLNILA%26s%3DBo3Be2WV5GqyHC8kND6XyVUGxKmlBkTNkA-6doO03hI%26e%3D&data=02%7C01%7C%7C82209bf522be415e5e1808d76396960a%7Ced5b36e701ee4ebc867ee03cfa0d4697%7C0%7C0%7C637087370721990027&sdata=C8vxkPpDKNGNuySytio3R4eckxs4MjHc3mMBDfMPFnY%3D&reserved=0>’. 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<mailto:archivesspace_api_doc_adhoc-bounces at lyralists.lyrasis.org>> on behalf of "Mayo, Dave" <dave_mayo at harvard.edu<mailto:dave_mayo at harvard.edu>>
Reply-To: ArchivesSpace API Ad Hoc Working Group <archivesspace_api_doc_adhoc at lyralists.lyrasis.org<mailto: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<mailto:archivesspace_api_doc_adhoc at lyralists.lyrasis.org>" <archivesspace_api_doc_adhoc at lyralists.lyrasis.org<mailto: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<mailto:dave_mayo at harvard.edu>>
Date: Tuesday, October 29, 2019 at 3:07 PM
To: "archivesspace_api_doc_adhoc at lyralists.lyrasis.org<mailto:archivesspace_api_doc_adhoc at lyralists.lyrasis.org>" <archivesspace_api_doc_adhoc at lyralists.lyrasis.org<mailto: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/<https://gcc02.safelinks.protection.outlook.com/?url=https%3A%2F%2Furldefense.proofpoint.com%2Fv2%2Furl%3Fu%3Dhttps-3A__archivesspace.github.io_archivesspace_user_building-2Dan-2Darchivesspace-2Drelease_%26d%3DDwMGaQ%26c%3DWO-RGvefibhHBZq3fL85hQ%26r%3D_Mv1dY22K7jvT5MD7xjbvGVzRDOUMhx4WYcnPSIzYnE%26m%3DmpB5LJB3R4GMPlWyg1r41u_Z1xC6kLtspH5OfqLNILA%26s%3DpsMfIOcg_3kzYGcmAdWix7dGYUSsoj4yeyxQ0l92swk%26e%3D&data=02%7C01%7C%7C82209bf522be415e5e1808d76396960a%7Ced5b36e701ee4ebc867ee03cfa0d4697%7C0%7C0%7C637087370721990027&sdata=ZEcRsiRMCtYiyFW%2B3b97i6fKujtBZ2qjl2ERfGn87cc%3D&reserved=0>
Docs for the build system: https://archivesspace.github.io/archivesspace/user/archivesspace-build-system/<https://gcc02.safelinks.protection.outlook.com/?url=https%3A%2F%2Furldefense.proofpoint.com%2Fv2%2Furl%3Fu%3Dhttps-3A__archivesspace.github.io_archivesspace_user_archivesspace-2Dbuild-2Dsystem_%26d%3DDwMGaQ%26c%3DWO-RGvefibhHBZq3fL85hQ%26r%3D_Mv1dY22K7jvT5MD7xjbvGVzRDOUMhx4WYcnPSIzYnE%26m%3DmpB5LJB3R4GMPlWyg1r41u_Z1xC6kLtspH5OfqLNILA%26s%3D3qxLeaNhNbJQU3l-FHZRRQ9TNOgn08VjFDYgD2gF5qk%26e%3D&data=02%7C01%7C%7C82209bf522be415e5e1808d76396960a%7Ced5b36e701ee4ebc867ee03cfa0d4697%7C0%7C0%7C637087370722000018&sdata=xyhVomAyMAz6NTxiI06PWpG82di%2BcDpnuEsedJtEYSg%3D&reserved=0>
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<https://gcc02.safelinks.protection.outlook.com/?url=https%3A%2F%2Furldefense.proofpoint.com%2Fv2%2Furl%3Fu%3Dhttps-3A__gcc02.safelinks.protection.outlook.com_-3Furl-3Dhttps-253A-252F-252Fgithub.com-252Farchivesspace-252Farchivesspace.git-26data-3D02-257C01-257C-257Ca805c2f7824d40acabb108d75e0496de-257Ced5b36e701ee4ebc867ee03cfa0d4697-257C0-257C0-257C637081246129619886-26sdata-3DtqyMhudCvLSJsXquOS0IHEwdExLTwEzZ6ohNe78WBzk-253D-26reserved-3D0%26d%3DDwMGaQ%26c%3DWO-RGvefibhHBZq3fL85hQ%26r%3D_Mv1dY22K7jvT5MD7xjbvGVzRDOUMhx4WYcnPSIzYnE%26m%3DmpB5LJB3R4GMPlWyg1r41u_Z1xC6kLtspH5OfqLNILA%26s%3D99zcgcWDfqE_wB1lhCwYJooG9-dHbHfqIF3U8QSD7dE%26e%3D&data=02%7C01%7C%7C82209bf522be415e5e1808d76396960a%7Ced5b36e701ee4ebc867ee03cfa0d4697%7C0%7C0%7C637087370722000018&sdata=8CgpNMkCPTcg2%2FPgAouAzjKK5hQqZ5bEhDWns3stFcQ%3D&reserved=0>
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 <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
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: <http://lyralists.lyrasis.org/pipermail/archivesspace_api_doc_adhoc/attachments/20191107/23d5a5eb/attachment-0001.html>
More information about the Archivesspace_api_doc_adhoc
mailing list