Documentation content

[danil-topchiy]

Set up documentation structure;
Add Introduction, Examples, api reference;

[danil-topchiy]

Based on #11, will rebase to master after #11 will be merged

[matejak]

This looks good so far, if you want to improve it, consider making the documentation based on tests - now, you have manually written some example code, but if you would include code from a test, it would guarantee that the code is always up-to-date, performing as expected. The sphinx literalinclude directive has huge possibilities in this regard, for example start-after and end-before (you can use special comments as anchors).

[danil-topchiy]

I also added code examples to example.py file and linked them in separate Examples page in documentation. Should I delete that file and link all the examples from tests ?
Thanks!

[matejak]

My point was that it may happen that the documentation falls out of sync with actual state, if it is not tested. Extracting the code into a separate file is surely a step forward, but if the example is not tested, then it is still not "there".
However, I feel that we are quite close - if you insert some asserts there, for example create a user, then assert that it exist when you list all users, you remove it, it doesn't exist etc., then you not only have a test for free, but users and readers exactly know what behavior to expect. And the only thing to figure out would be how to include that in an actual test.
But I think that sharing the file to a container and executing it using the python interpreter should do the trick - it just has to be documented in the test README.

[danil-topchiy]

I understand. I added asserts to example.py code and linked it in Introduction as quick start examples and it looks good.
Should we include examples of all methods like this in separate Examples page in documentation on the beginning of the project? Because it will take a lot of time and will be almost the same as copy-pasting tests but without self.nxc and asserts in between the code.

[matejak]

Of course not, you are right - no copy pasting! I like changes to the example. Let's stick with it for the time being, more docs can always be added in another PR.

[matejak]

I have also noticed that the conf.py uses the alabaster theme, if you swap it to default, it will stay alabaster locally, and it will look nice on readthedocs, where it will use their theme. Or you can use a construct like this:

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
html_theme = 'alabaster'

if ON_RTD:
    html_theme = 'default'

[matejak]

This looks pretty good, please rebase so it is clearly visible what got added. I feel that this is close to being merged.

[scrutinizer-notifier]

The inspection completed: 1 new issues

[danil-topchiy]

@matej rebased against master

[matejak]

Good job, merging.

[matejak]

Nice, check out https://nextcloud-api.readthedocs.io/en/latest/ !

[danil-topchiy]

Much better now! However, examples and api index page still needs improvement.