Update ADC docs for v1.2 (AIRR v1.4)

[bcorrie]

Closes #597 #605

[bcorrie]

@schristley do you want to have a look at this? Basic sections for new API entry points now exist.

[schristley]

Enabled branch on RTD.

• [x] The CellExpression schema has title of Cell instead.
• [x] Doesn't look like airr/v1/expression/{expression_id} is in the API spec?
• [x] Receptor schema link is not active.
• [x] CellExpression schema seems to be missing from the AIRR Data Model with the other schemas.

Otherwise looks good.

[bussec]

@schristley

Receptor schema link is not active.

It will be introduced via #404, so it should be fine as long as we merge both of them soon.

[bcorrie]

• The CellExpression schema has title of Cell instead.

@schristley I can't find where this occurs???

[bcorrie]

• Doesn't look like airr/v1/expression/{expression_id} is in the API spec?

Nice catch, fixed.

[schristley]

• The CellExpression schema has title of Cell instead.

@schristley I can't find where this occurs???

From the endpoints table, there is a link to the CellExpression schema

[bcorrie]

• CellExpression schema seems to be missing from the AIRR Data Model with the other schemas.

Sorry - not clear what is missing here. Is this in the docs or in the actual schema?

[schristley]

In the docs, https://docs.airr-community.org/en/adc-docs/datarep/overview.html

[bcorrie]

In the docs, https://docs.airr-community.org/en/adc-docs/datarep/overview.html

Fixed, thanks. @schristley @bussec @javh can you take a look at the wording I used here. Not sure my one sentence description of these objects are going to be correct. In particular, I am not sure how to describe Receptor or Clone correctly.

[schristley]

Need to update conf.py and stick in the bit of code to insert the schema table.

[bcorrie]

So are the schemas that we are adding for v1.4 really still "Experimental" as per the above Docs pages? How do they become not "Experimental" if not through an official release?

[bcorrie]

I am not sure how the conf.py works and what pages it generates. Can someone enlighten me - or if it is easy make the changes.

[bcorrie]

OK, I think I have it... If anyone wants to make any changes to the overview page and the high level description of these objects, let me know. Otherwise I will merge later today...

In the docs, https://docs.airr-community.org/en/adc-docs/datarep/overview.html

Fixed, thanks. @schristley @bussec @javh can you take a look at the wording I used here. Not sure my one sentence description of these objects are going to be correct. In particular, I am not sure how to describe Receptor or Clone correctly.

[javh]

So are the schemas that we are adding for v1.4 really still "Experimental" as per the above Docs pages? How do they become not "Experimental" if not through an official release?

Yeah, they are still experimental. It's fuzzy, but they exit "Experimental" when they become stable. Ie, we stop messing with them except for minor updates, we start caring about breaking backwards compatibility, they are well tested, etc.

They enter "Experimental" when we put them in a release and make them available to the public to experiment with. "Experimental" status is a disclaimer that while schema is a usable draft, it isn't stable.

[bcorrie]

So are the schemas that we are adding for v1.4 really still "Experimental" as per the above Docs pages? How do they become not "Experimental" if not through an official release?

Yeah, they are still experimental. It's fuzzy, but they exit "Experimental" when they become stable. Ie, we stop messing with them except for minor updates, we start caring about breaking backwards compatibility, they are well tested, etc.

They enter "Experimental" when we put them in a release and make them available to the public to experiment with. "Experimental" status is a disclaimer that the schema isn't stable.

OK, gotcha... So a goal would probably be to have all of our current "Experimental" schemas/apis as non-Experimental for the 2.0 release.

[bcorrie]

Closes #605

[javh]

Ideally, yeah, they are experimental for a release then they become production ready in the next release. But, that doesn't happen often in practice. Alignment is still experimental and probably always will be, because there doesn't seem to be much of a use case, so there's no point in finalizing it and no real way to test it if we did.

[bussec]

@bcorrie LGTM, do you want to merge this before or after I merge #404?

[bcorrie]

Sounds like less work for me if I merge first 8-)

[bcorrie]

I will pull the trigger now...