Xen project Mailing List

@Simon: need your input further down! I am not 100% sure what your thinking on Sphinx docstring annotations in C files are

On 17 Feb 2018, at 19:21, Ray LI <ray4opensource@xxxxxxxxx> wrote:

Hi Lars,

I have almost finished proposing a patch about user's document, but I met a problem when I sent emails to the list. But I am going to try to figure it out tomorrow.

Seems you have resolved this for now. Congratulations for the patch.

I will send some feedback: this may feel a bit nit-picky, but is not.

It will also mean, you have to send out a v2 of the patch: which you will have to deal with in subsequent patches.

As for that small task, if I understood it correctly, the task is made up with two parts,

Let's try and refine this:

There is already a makefile for Sphinx based docs: see [unikraft/unikraft.git] / doc / Makefile which generates the doc set in http://unikraft.neclab.eu

It runs over the doc directory, which is nicely self-contained in the doc directory.

API documentation is different, because

a) you have API annotations called "docstrings" in source files across an an entire repository (example annotations are in http://www.sphinx-doc.org/en/stable/ext/autodoc.html)

b) you are going to have to invoke sphinx-apidoc on source files in that repository (see http://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html, https://romanvm.pythonanywhere.com/post/autodocumenting-your-python-code-sphinx-part-ii-6/ - includes a neat stand-alone example project) to do this, support would have to be added to unikraft.git / Makefile

Note that [unikraft/unikraft.git] / doc / Makefile is based on that example (you can check the diffs via https://www.diffnow.com/: URL1=https://raw.githubusercontent.com/romanvm/sphinx_tutorial/master/docs/Makefile. URL2=http://xenbits.xen.org/gitweb/?p=unikraft/unikraft.git;a=blob_plain;f=doc/Makefile;h=bb1480bb59cf24bcba054a2e6487f13a35e608b9;hb=HEAD)

Now there is a problem potentially with a), as docstrings are not C compatible: they are essentially Python constructs, but Unikraft is primarily C based. There are two ways two address this:

1) embed docstrings in C comments and run sphinx-apidoc on the sources, but there would be no autodoc support and I don't know whether the output would actually be useful

2) use doxygen annotation and use something like https://breathe.readthedocs.io to generate the API documentation such that it can be merged with the Sphinx docs we already have

And there are some design choices for b)

3) We could add docs related rules in unikraft.git / Makefile (from line 437)

4) You could use "make print-srcs" to get the source files. You would then run sphinx-apidoc or doxygen with breathe on the source files. Ideally this process would be encoded as a rule from within [unikraft/unikraft.git] / doc / Makefile

@Simon: has any thinking gone into this?

It seems to me that this could become too big for a small starter project.

In any case, there are some design questions that you are needed for.

@Ray:

You may want to check out https://www.slideshare.net/shimizukawa/sphinx-autodoc-automated-api-documentation-pyconapac2015:

kind of a good overview on Sphinx for Python, but does not address the issues around a)

In addition:

* Play with the docs build in: [unikraft/unikraft.git] / doc / Makefile - you should have done this already re your other patch

* I would play a bit with "make print-srcs"

* As a stretch goal, you could think about how to approach something like 4

* See whether running sphinx-apidoc on C source files with embedded "docstrings" (wrapped in C style comments) produces anything sensible

With this in mind: I think for anything further, we have to wait for Simon to respond.

Write some text document about the build system API.

Use sphinx to generate the API documentation.

And the final result of it is like user's guide. Is that correct?

I think I covered this above.

Best Regards

Lars

Re: [Minios-devel] About Outreachy intern contribution for "Enhanced Profiling and Tracing Support for Unikraft"