Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Any ideas to improve the documentation? #2245

Open
gabrieldemarmiesse opened this issue May 5, 2018 · 25 comments
Open

Any ideas to improve the documentation? #2245

gabrieldemarmiesse opened this issue May 5, 2018 · 25 comments

Comments

@gabrieldemarmiesse
Copy link
Contributor

gabrieldemarmiesse commented May 5, 2018

Hi!

I have some time to dedicate to the documentation, but it's hard to know where to improve, or even what is the vision that the Cython maintainers have for the documentation.

Please comment and give me what improvements you would like to see in the documentation. I'll do my best to make them.

NOTE: I have been reading this thread already: http://www.mail-archive.com/cython-dev@codespeak.net/msg06945.html but I think that many things have changed and been done since, so I'm asking again to avoid getting my pull requests rejected.

@scoder
Copy link
Contributor

scoder commented May 7, 2018

Well, yes, there is a long-standing issue: the separation between the "users guide" and the "reference guide", most importantly for the "Language Basics" and "Extension Types" chapters. Both sides are not entirely in sync, and there is no real reason why there needs to be a reference guide in the first place.

There are a few drawbacks: removing parts of the documentation will leave stale links on the web, and filling the users guide with additional information may actually make it more difficult for new users to understand. But the current duplication also makes it difficult for users to find what they are looking for, so I doubt that there is a big risk of making things worse.

So, I can't say if this is a task that you would consider. It's definitely not a small task, but it's something that can be done incrementally, one thing at a time. In the end, I'd be happy if the reference guide pages were reduced to a simple placeholder link back to the respective users guide page that replaces them.

Would that be something you'd want to try?

@gabrieldemarmiesse
Copy link
Contributor Author

Well, we'll see how far I can go. As you said, this can be done incrementally, so there is no worries about work being wasted.

Can I remove the text from the sections in the reference guide as I progress and replace it with a link to the corresponding sections in the user guide? Or should I remove the text from the reference guide only when everything is done? What do you prefer?

@scoder
Copy link
Contributor

scoder commented May 7, 2018

I would say, since we can't be sure that you can get everything migrated in one go, leave the content in the reference guide, but add a marker comment (e.g. ".. NOW IN USER GUIDE, DO NOT TOUCH", i.e. not visible in the HTML) to the sections that you finish merging, so that they are easy to delete afterwards.

@gabrieldemarmiesse
Copy link
Contributor Author

Would putting a link instead be better? So that users have access only to the up to date version of the documentation. See #2248 . I understand if you still want to keep the text though.

@gabrieldemarmiesse
Copy link
Contributor Author

gabrieldemarmiesse commented May 7, 2018

I made two PR, #2248 and #2249 . Pick the one you prefer.

@scoder
Copy link
Contributor

scoder commented May 8, 2018

To be clear, I really only want to achieve three things here:

  • allow you to work efficiently without imposing much overhead, but:
  • keep the documentation in a useful and readable state, regardless of how far you get with it
  • make it easy to clean things up afterwards, without having to check again what can safely be deleted

If you have a better idea how to do this, I'll be happy to hear it. Otherwise, I'd stick with "keep+comment" (i.e. #2249), and then delete only whole sections after migrating them. What do you think?

@gabrieldemarmiesse
Copy link
Contributor Author

I'm okay with this. I'm on it then!

@gabrieldemarmiesse
Copy link
Contributor Author

I made all the PRs relative to the language basics. Once they are all merged or rejected, we can consider the language basics page completely transferred to the user guide.

@gabrieldemarmiesse
Copy link
Contributor Author

For history purposes and book keeping, we are talking about the following PRs:

#2250
#2262
#2261
#2260
#2259
#2258
#2257
#2256
#2255
#2254
#2253

@scoder
Copy link
Contributor

scoder commented May 10, 2018

Great, thanks a lot!
Give me a couple of days to find the time for looking through them.

@gabrieldemarmiesse
Copy link
Contributor Author

Of course. I did it all in one run because it was simpler for me to keep track of what goes where, but let's take our time to make it accurate and helpful for users.

@gabrieldemarmiesse
Copy link
Contributor Author

gabrieldemarmiesse commented May 15, 2018

After the #2260 is merged, shall we remove the text from the language basics in the reference guide and replace it with links to the corresponding sections in the userguide?

The only PR that wasn't merged is #2257 but it only represent a transfer of those lines:

Function Pointers
=================

* Functions declared in a ``struct`` are automatically converted to function pointers.
* see **using exceptions with function pointers**

and Using exceptions with function pointers doesn't exist, so I don't think we loose much information.

@scoder
Copy link
Contributor

scoder commented May 17, 2018

remove the text from the language basics in the reference guide

Yes. Happily so! :)

replace it with links to the corresponding sections in the userguide?

I think that would be perfect.

"using exceptions with function pointers"

I think this refers to the "Error and Exception Handling" section. It has a note on function pointers.

For now, I think the information in the "Function Pointers" section could be moved over as well. It's a short section then, ok, but at least it's there then.

@scoder
Copy link
Contributor

scoder commented May 18, 2018

I also just remembered #1921 as a documentation issue, which has long been languishing. Would be great if you look into getting it ready for merging. Most of my comments look like minor issues.

@gabrieldemarmiesse
Copy link
Contributor Author

Thanks for the tip. It's on the TODO list then.

@gabrieldemarmiesse
Copy link
Contributor Author

The pull request which concluded the transfer of the language basics from the reference guide to the userguide is #2275 .

This message is to keep a trace of the logic in the changes to the docs.

@gabrieldemarmiesse
Copy link
Contributor Author

The section Dynamic attributes was actually the only one that wasn't ported to the userguide in extension types.
The PR #2277 fixes this.

All the sections of reference/extension_types.rst are either in userguide/extension_types.rst or in userguide/special_methods.rst.

Once the PR has been merged, I'll replace the text in the reference guide by links to the corresponding sections in the userguide.

@scoder
Copy link
Contributor

scoder commented May 18, 2018

Did you verify that all the information in the reference guide sections is also included in the corresponding user guide sections?

@gabrieldemarmiesse
Copy link
Contributor Author

gabrieldemarmiesse commented May 18, 2018

The only piece of information that wasn't transferred was a note in the section Initialization cinit and init

Note that all constructor arguments will be passed as Python objects.
This implies that non-convertible C types such as pointers or C++ objects
cannot be passed into the constructor from Cython code.  If this is needed,
use a factory function instead that handles the object initialisation.
It often helps to directly call ``__new__()`` in this function to bypass the
call to the ``__init__()`` constructor.

Should I make a similar note in the same section in the userguide?

@scoder
Copy link
Contributor

scoder commented May 18, 2018

Yes, please.

@gabrieldemarmiesse
Copy link
Contributor Author

Sure thing.

@gabrieldemarmiesse
Copy link
Contributor Author

The PR #2278 fixes this.

@gabrieldemarmiesse
Copy link
Contributor Author

gabrieldemarmiesse commented May 20, 2018

The PR completing the transfer of the extension types from the reference guide to the userguide is #2284

After it is merged, what shall we do with the compilation page in the reference guide?

@scoder
Copy link
Contributor

scoder commented May 21, 2018

I actually like the idea of keeping example code outside of the ReST files and integrate them into the test suite somehow. Not big tests, just to make sure each of the files is syntax tested and not completely broken. The include paths are easy enough to grep for usages of the example files.

@gabrieldemarmiesse
Copy link
Contributor Author

Any preference for the layout of the example directory?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants