[Archivesspace_api_doc_adhoc] Question about routes and examples

[David W. Hodges]

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 <dave_mayo at harvard.edu> 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: *<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
>
>
> _______________________________________________
> 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: <http://lyralists.lyrasis.org/pipermail/archivesspace_api_doc_adhoc/attachments/20200920/42c9245f/attachment.html>