Open Stack

On Wed, Nov 4, 2015 at 5:31 PM, Sean M. Collins <sean at coreitpro.com> wrote:

> Hi,
>
> During the review of https://review.openstack.org/#/c/240815, I started
> to think about how there are some very specific changes to the Neutron
> API that are getting flagged with DocImpact, and contributors are
> attempting to add them to the Networking Guide.
>
> Specifically, 240815 attempts to add information about cases where a
> user supplied MAC address fails validation at the Neutron API layer, and
> an error is returned.
>
> The specific MAC addresses that are being rejected are a little in the
> weeds, technically. The MAC addresses 00:00:00:00:00:00 and
> FF:FF:FF:FF:FF:FF are special addresses (look up RFC7042 if you are a
> masochist for more information). It is not normal to assign those MAC
> addresses, so Neutron does not allow you to.
>
> Suffice to say, this is a fairly technical bit of literature, and may
> not really belong in the Networking Guide.
>
> Ideally, it would be part of some sort of  API documentation, however I
> am a little fuzzy on what the status of the API reference is today.
>
> There is http://developer.openstack.org/api-ref-networking-v2.html -
> although is that maintained? I've noticed a lot of gaps in it when
> consulting it from time to time.
>
>
Yes, that is maintained (badly) and sourced (for sure) from
https://github.com/openstack/api-site.


> I know for a while there was an import done into the neutron-specs repo,
> but it hasn't really ever been touched since the first import, and the
> RST conversion was not really complete, a lot of the tables did not
> survive the RST conversion experience.
>
>
> https://github.com/openstack/neutron-specs/commit/eebdf8b039713e58b60b3d9b4bbb5fae5bb5645b
>
> More recently, those files were shuffled into a different part of the
> repo
>
>
> https://github.com/openstack/neutron-specs/commit/415f1eaf5b94fe623ccf7c53dbc26ef3fc798e34
>
> However that's the most that has been done - just moved around. I don't
> think there has been any change to the content.
>
>
For the Compute API I've been working on two patches to try to get their
equivalent to neutron-specs API docs built to developer.openstack.org:
https://review.openstack.org/#/c/230186/
https://review.openstack.org/#/c/231000/



> So - where does detailed API documentation live?
>
>
In api-site and neutron-specs repos both, and we need to maintain and
update both.


> Anyway, please forgive the ignorance, I'm sure this has probably been
> discussed elsewhere and I'm just not aware.
>

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.

Anne

1.
http://specs.openstack.org/openstack/docs-specs/specs/liberty/api-site.html


>
> --
> Sean M. Collins
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20151104/60e9f88f/attachment.html>