<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Nov 4, 2015 at 5:31 PM, Sean M. Collins <span dir="ltr"><<a href="mailto:sean@coreitpro.com" target="_blank">sean@coreitpro.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">Hi,<br>
<br>
During the review of <a href="https://review.openstack.org/#/c/240815" rel="noreferrer" target="_blank">https://review.openstack.org/#/c/240815</a>, I started<br>
to think about how there are some very specific changes to the Neutron<br>
API that are getting flagged with DocImpact, and contributors are<br>
attempting to add them to the Networking Guide.<br>
<br>
Specifically, 240815 attempts to add information about cases where a<br>
user supplied MAC address fails validation at the Neutron API layer, and<br>
an error is returned.<br>
<br>
The specific MAC addresses that are being rejected are a little in the<br>
weeds, technically. The MAC addresses 00:00:00:00:00:00 and<br>
FF:FF:FF:FF:FF:FF are special addresses (look up RFC7042 if you are a<br>
masochist for more information). It is not normal to assign those MAC<br>
addresses, so Neutron does not allow you to.<br>
<br>
Suffice to say, this is a fairly technical bit of literature, and may<br>
not really belong in the Networking Guide.<br>
<br>
Ideally, it would be part of some sort of  API documentation, however I<br>
am a little fuzzy on what the status of the API reference is today.<br>
<br>
There is <a href="http://developer.openstack.org/api-ref-networking-v2.html" rel="noreferrer" target="_blank">http://developer.openstack.org/api-ref-networking-v2.html</a> -<br>
although is that maintained? I've noticed a lot of gaps in it when<br>
consulting it from time to time.<br>
<br></blockquote><div><br></div><div>Yes, that is maintained (badly) and sourced (for sure) from <a href="https://github.com/openstack/api-site">https://github.com/openstack/api-site</a>.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
I know for a while there was an import done into the neutron-specs repo,<br>
but it hasn't really ever been touched since the first import, and the<br>
RST conversion was not really complete, a lot of the tables did not<br>
survive the RST conversion experience.<br>
<br>
<a href="https://github.com/openstack/neutron-specs/commit/eebdf8b039713e58b60b3d9b4bbb5fae5bb5645b" rel="noreferrer" target="_blank">https://github.com/openstack/neutron-specs/commit/eebdf8b039713e58b60b3d9b4bbb5fae5bb5645b</a><br>
<br>
More recently, those files were shuffled into a different part of the<br>
repo<br>
<br>
<a href="https://github.com/openstack/neutron-specs/commit/415f1eaf5b94fe623ccf7c53dbc26ef3fc798e34" rel="noreferrer" target="_blank">https://github.com/openstack/neutron-specs/commit/415f1eaf5b94fe623ccf7c53dbc26ef3fc798e34</a><br>
<br>
However that's the most that has been done - just moved around. I don't<br>
think there has been any change to the content.<br>
<br></blockquote><div><br></div><div> For the Compute API I've been working on two patches to try to get their equivalent to neutron-specs API docs built to <a href="http://developer.openstack.org">developer.openstack.org</a>:<br></div><div><a href="https://review.openstack.org/#/c/230186/">https://review.openstack.org/#/c/230186/</a><br></div><div><a href="https://review.openstack.org/#/c/231000/">https://review.openstack.org/#/c/231000/</a><br></div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
So - where does detailed API documentation live?<br>
<br></blockquote><div><br></div><div>In api-site and neutron-specs repos both, and we need to maintain and update both.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
Anyway, please forgive the ignorance, I'm sure this has probably been<br>
discussed elsewhere and I'm just not aware.<br></blockquote><div><br></div><div>Keep an eye on the work with fairy-slipper and the spec [1] to rework API docs. We got the proof-of-concept done last release and this release we'll continue the efforts. </div><div><br></div><div>Anne</div><div><br></div><div>1. <a href="http://specs.openstack.org/openstack/docs-specs/specs/liberty/api-site.html">http://specs.openstack.org/openstack/docs-specs/specs/liberty/api-site.html</a></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<span class=""><font color="#888888"><br>
--<br>
Sean M. Collins<br>
<br>
_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
</font></span></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature"><div dir="ltr"><div>Anne Gentle</div><div>Rackspace</div><div>Principal Engineer</div><div><a href="http://www.justwriteclick.com" target="_blank">www.justwriteclick.com</a></div></div></div>
</div></div>