[Archivesspace_api_doc_adhoc] Question about routes and examples

[Mayo, Dave]

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: <archivesspace_api_doc_adhoc-bounces at lyralists.lyrasis.org> on behalf of "David W. Hodges" <dwh2128 at columbia.edu>
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<https://urldefense.proofpoint.com/v2/url?u=https-3A__archivesspace.github.io_archivesspace_api_-3Fshell-23get-2Da-2Dlist-2Dof-2Dsystem-2Dusers&d=DwMFaQ&c=WO-RGvefibhHBZq3fL85hQ&r=_Mv1dY22K7jvT5MD7xjbvGVzRDOUMhx4WYcnPSIzYnE&m=lXXvcKi5ALsf7jeGlOk3EwMIOxz7Yo8ymlyFcn9GTxM&s=j7X0iyj357P3BU0v0VQcCgH98PnLZMimRGInlfCTDkU&e=>" shows a simple Curl example. But looking at users.rb<https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_archivesspace_archivesspace_blob_master_backend_app_controllers_users.rb-23L70&d=DwMFaQ&c=WO-RGvefibhHBZq3fL85hQ&r=_Mv1dY22K7jvT5MD7xjbvGVzRDOUMhx4WYcnPSIzYnE&m=lXXvcKi5ALsf7jeGlOk3EwMIOxz7Yo8ymlyFcn9GTxM&s=mZJ5zna87MBEhFDoyM8CbE3CsjXUSI5ndjmk90yVI_E&e=>, 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: <http://lyralists.lyrasis.org/pipermail/archivesspace_api_doc_adhoc/attachments/20200920/072594e7/attachment-0001.html>