From dwh2128 at columbia.edu Sun Sep 20 11:10:17 2020 From: dwh2128 at columbia.edu (David W. Hodges) Date: Sun, 20 Sep 2020 11:10:17 -0400 Subject: [Archivesspace_api_doc_adhoc] Question about routes and examples Message-ID: Hi all. OK, after some struggle I managed to build the docs anew on my Mac. So far so good! (BTW, if anyone is good at this on Linux I'd appreciate any help, as I tried on Ubuntu but ran into a cascade of errors and gave up; I'd like to get this working on that machine eventually though.) Looking at a few routes, I am unsure where exactly the code examples are (or should be) stored. In some cases the code is in the .rb file, but in others it isn't. For example, the entry for "Get a list of system users " shows a simple Curl example. But looking at users.rb , there is no .example code that I can find. Whereas in other routes like Dave showed, the examples are right there in the controller adjacent to the other route documentation. I recall something about the "prepend" attribute and determining whether things overwrite existing documentation or not (presumably in the markdown file index.md, I guess?). Is that what's going on here? I had thought the markdown was generated downstream from the controllers, but is it more of a merge from two different sources? And for the sake of maintainability, should we strive to make the documentation more uniform and single-source? I'm not really familiar with best practices here, just wondering more from a documentation management perspective. Any hints would be appreciated. If this is all covered in the video tutorials I'll go back and listen more carefully ;) Thanks, I'm looking forward to getting started for real and making progress! David -- David W. Hodges Special Collections Analyst Columbia University Libraries Butler Library 535 West 114th St. New York, NY 10027 212 854-8758 -------------- next part -------------- An HTML attachment was scrubbed... URL: From dave_mayo at harvard.edu Sun Sep 20 14:00:38 2020 From: dave_mayo at harvard.edu (Mayo, Dave) Date: Sun, 20 Sep 2020 18:00:38 +0000 Subject: [Archivesspace_api_doc_adhoc] Question about routes and examples In-Reply-To: References: Message-ID: I think it?s briefly covered in the video tutorials, but there?s no reason you should have to go pick through them. To summarize, the examples are actually built during the build process that generates the documentation. Specifically, they?re created using the FactoryBot test mock factories (defined here https://github.com/archivesspace/archivesspace/blob/master/backend/spec/factories.rb), during the portion of building the docs that lives in the test harness (here: https://github.com/archivesspace/archivesspace/blob/master/backend/spec/documentation_spec.rb). This gets saved to two files, I believe in the root directory of the project: endpoint_examples.json. endpoint_examples_problems.json The examples that show up defined in code are the ones that someone?s added to override the ones generated automatically by this method, i.e. the thing we?re doin? in this project! The automated _documentation_, on the other hand, Is generated based on properties of the endpoint (i.e. whether it?s paginated or deprecated) and is in the ERB template that generates the Slate documentation. I can describe it in more depth if need be, but fundamentally I think the mechanism doesn?t matter to the project ? I?d recommend just looking at the published docs to see if the examples or documentation are sufficient, and then going to the code or putting docs/examples in the spreadsheet as needed. -- Dave Mayo (he/him) Senior Digital Library Software Engineer Harvard University > HUIT > LTS From: on behalf of "David W. Hodges" Reply-To: "archivesspace_api_doc_adhoc at lyralists.lyrasis.org" Date: Sunday, September 20, 2020 at 11:10 AM To: "archivesspace_api_doc_adhoc at lyralists.lyrasis.org" Subject: [Archivesspace_api_doc_adhoc] Question about routes and examples Hi all. OK, after some struggle I managed to build the docs anew on my Mac. So far so good! (BTW, if anyone is good at this on Linux I'd appreciate any help, as I tried on Ubuntu but ran into a cascade of errors and gave up; I'd like to get this working on that machine eventually though.) Looking at a few routes, I am unsure where exactly the code examples are (or should be) stored. In some cases the code is in the .rb file, but in others it isn't. For example, the entry for "Get a list of system users" shows a simple Curl example. But looking at users.rb, there is no .example code that I can find. Whereas in other routes like Dave showed, the examples are right there in the controller adjacent to the other route documentation. I recall something about the "prepend" attribute and determining whether things overwrite existing documentation or not (presumably in the markdown file index.md, I guess?). Is that what's going on here? I had thought the markdown was generated downstream from the controllers, but is it more of a merge from two different sources? And for the sake of maintainability, should we strive to make the documentation more uniform and single-source? I'm not really familiar with best practices here, just wondering more from a documentation management perspective. Any hints would be appreciated. If this is all covered in the video tutorials I'll go back and listen more carefully ;) Thanks, I'm looking forward to getting started for real and making progress! David -- David W. Hodges Special Collections Analyst Columbia University Libraries Butler Library 535 West 114th St. New York, NY 10027 212 854-8758 -------------- next part -------------- An HTML attachment was scrubbed... URL: From dwh2128 at columbia.edu Sun Sep 20 20:33:53 2020 From: dwh2128 at columbia.edu (David W. Hodges) Date: Sun, 20 Sep 2020 20:33:53 -0400 Subject: [Archivesspace_api_doc_adhoc] Question about routes and examples In-Reply-To: References: Message-ID: OK thanks! I'll try updating a few locally and see how it goes. d On Sun, Sep 20, 2020 at 2:00 PM Mayo, Dave wrote: > I think it?s briefly covered in the video tutorials, but there?s no reason > you should have to go pick through them. > > > > To summarize, the examples are actually built during the build process > that generates the documentation. Specifically, they?re created using the > FactoryBot test mock factories (defined here > https://github.com/archivesspace/archivesspace/blob/master/backend/spec/factories.rb), > during the portion of building the docs that lives in the test harness > (here: > https://github.com/archivesspace/archivesspace/blob/master/backend/spec/documentation_spec.rb > ). > > > > This gets saved to two files, I believe in the root directory of the > project: > > endpoint_examples.json. > > endpoint_examples_problems.json > > The examples that show up defined in code are the ones that someone?s > added to override the ones generated automatically by this method, i.e. the > thing we?re doin? in this project! > > > > The automated _*documentation*_, on the other hand, Is generated based on > properties of the endpoint (i.e. whether it?s paginated or deprecated) and > is in the ERB template that generates the Slate documentation. I can > describe it in more depth if need be, but fundamentally I think the > mechanism doesn?t matter to the project ? I?d recommend just looking at the > published docs to see if the examples or documentation are sufficient, and > then going to the code or putting docs/examples in the spreadsheet as > needed. > > > > -- > > Dave Mayo (he/him) > > Senior Digital Library Software Engineer > Harvard University > HUIT > LTS > > > > *From: * on > behalf of "David W. Hodges" > *Reply-To: *"archivesspace_api_doc_adhoc at lyralists.lyrasis.org" < > archivesspace_api_doc_adhoc at lyralists.lyrasis.org> > *Date: *Sunday, September 20, 2020 at 11:10 AM > *To: *"archivesspace_api_doc_adhoc at lyralists.lyrasis.org" < > archivesspace_api_doc_adhoc at lyralists.lyrasis.org> > *Subject: *[Archivesspace_api_doc_adhoc] Question about routes and > examples > > > > Hi all. OK, after some struggle I managed to build the docs anew on my > Mac. So far so good! (BTW, if anyone is good at this on Linux I'd > appreciate any help, as I tried on Ubuntu but ran into a cascade of errors > and gave up; I'd like to get this working on that machine eventually > though.) > > > > Looking at a few routes, I am unsure where exactly the code examples are > (or should be) stored. In some cases the code is in the .rb file, but in > others it isn't. For example, the entry for "Get a list of system users > " > shows a simple Curl example. But looking at users.rb > , > there is no .example code that I can find. Whereas in other routes like > Dave showed, the examples are right there in the controller adjacent to the > other route documentation. > > > > I recall something about the "prepend" attribute and determining whether > things overwrite existing documentation or not (presumably in the markdown > file index.md, I guess?). Is that what's going on here? I had thought the > markdown was generated downstream from the controllers, but is it more of a > merge from two different sources? > > > > And for the sake of maintainability, should we strive to make the > documentation more uniform and single-source? I'm not really familiar with > best practices here, just wondering more from a documentation management > perspective. > > > > Any hints would be appreciated. If this is all covered in the video > tutorials I'll go back and listen more carefully ;) > > > > Thanks, I'm looking forward to getting started for real and making > progress! > > > > David > > > > -- > > David W. Hodges > > Special Collections Analyst > > Columbia University Libraries > > Butler Library > > 535 West 114th St. > > New York, NY 10027 > > 212 854-8758 > > > _______________________________________________ > Archivesspace_api_doc_adhoc mailing list > Archivesspace_api_doc_adhoc at lyralists.lyrasis.org > http://lyralists.lyrasis.org/mailman/listinfo/archivesspace_api_doc_adhoc > -- David W. Hodges Special Collections Analyst Columbia University Libraries Butler Library 535 West 114th St. New York, NY 10027 212 854-8758 -------------- next part -------------- An HTML attachment was scrubbed... URL: