There is a preview at github:git https://gist.github.com/yangl1996/af7ce793b81e79ce52f3

I see a lot of overlap with what's in https://pagure.io/api/0/ and a little too much for my taste as it means we need to keep both resources in sync.

What I am thinking we could do (these are options up to changes if you like):

• Drop the description of the endpoints from this doc, it is not needed nor do we want to maintain the documentation twice
• Maybe improve the current documentation with the style and layout you used, it looks quite nice :)
• Then, we'll need to find a way to embed the top part of this document into https://pagure.io/api/0/ as well

What do you think of all this?

I see a lot of overlap with what's in https://pagure.io/api/0/ and a little too much for my taste as it means we need to keep both resources in sync.
What I am thinking we could do (these are options up to changes if you like):

Drop the description of the endpoints from this doc, it is not needed nor do we want to maintain the documentation twice
Maybe improve the current documentation with the style and layout you used, it looks quite nice :)
Then, we'll need to find a way to embed the top part of this document into https://pagure.io/api/0/ as well

What do you think of all this?

Yes, I totally agree with you. If we want to keep /api/0/, then we don't need to display the info once again in this doc ;)

The api reference part of this doc comes from mostly /api/0/ and some from unit test. The part from /api/0/ is almost identical with it. So maybe we can use this content to replace the /api/0/? We can change /api/0/ to a small site like https://developer.github.com/v3/ , so we can organize this doc in better way. And later on we can also add webhook doc to it (I am planning to write webhook doc).

What's your idea?

Well, the content in /api/0/ comes directly from the sources code. In the future we may split the doc out, but in this case it will likely be via the doc git repo and maybe with a script to extract the docstrings we currently have to generate the API documentation page.

What do you think?

Well, the content in /api/0/ comes directly from the sources code. In the future we may split the doc out, but in this case it will likely be via the doc git repo and maybe with a script to extract the docstrings we currently have to generate the API documentation page.
What do you think?

I got it ;)

Shall we fix the missing endpoints in /api/0/, and try to replace the layout of /api/0/ to this one's? And drop the description of endpoints in this doc, only keep the top part. Later we can work out a way to embed the top part into /api/0/.

What's your idea? If this works, I'll first modify the docstrings ;)

Shall we fix the missing endpoints in /api/0/, and try to replace the layout of /api/0/ to this one's? And drop the description of endpoints in this doc, only keep the top part. Later we can work out a way to embed the top part into /api/0/.

Def :thumbsup: on this :)

Updated the docstrings and the api.rst

I found that in the source code there is no missing endpoint, but on pagure.io/api/0/ there are some missing ones, maybe pagure.io is not running the latest code. There is some missing parameters in the source code, and I got them fixed ;)

I would keep the second line, after all we're below the title so in a place where we can be more descriptive about this endpoint.

Basically, I saw the title as a way to present quickly what this endpoint is, and the text below it would be a longer description of this endpoint, what it does, why and so on :)

cf below in fact

I used to use arg for mandatory arguments and kwarg for optional ones.
Is there a way we could make this clear in the new table?

We'll have to see how it looks in the UI, but if we can, I'd like to try keeping the 80 chars limit as this is also a docstring :)

Required before optional?

Are we returning a dict or JSON?

A few comments otherwise looks good :)

One question: which endpoints are missing in /api/0/ ? (We can fix them, here or in a separate PR if you prefer, the file to adjust is /api/__init__.py

A few comments otherwise looks good :)
One question: which endpoints are missing in /api/0/ ? (We can fix them, here or in a separate PR if you prefer, the file to adjust is /api/init.py

I found that no endpoints are missing in the source code. I was comparing the online version of pagure.io/api/0/, and found "get single issue" and "get single user" were missing. But in the source code they are not missing, maybe because the online version is not built from the latest code ;-)

Thank you very much for the comments! I'll fix them at July 4. I have my last two final exams on July 2 and July 3 and now busy preparing for it :)

pagure.io is running code that is about a week old but as far as I can see, there was no changes to the API since, so this needs to be fixed

Currently I add Required in the table's description. Changing to add a column to specify this as this info is important

all fixed ;)

Extra | ?

The extra '|' is a sign of continuation line, and the whole block will be parsed as a single line :)

Didn't know that cool!

I'll test the changes locally and eventually merge it outside of pagure to keep the history linear :)

I discovered that also today when trying to keep the lines short ;)

I'll test the changes locally and eventually merge it outside of pagure to keep the history linear :)

Sure! Thanks :)

Ok I adjusted a couple of things behind it, but it looked good and I merged it manually

Ok I adjusted a couple of things behind it, but it looked good and I merged it manually

Cool! :)