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

Documentation overhaul #46

Open
tomasaschan opened this issue Jul 18, 2015 · 6 comments
Open

Documentation overhaul #46

tomasaschan opened this issue Jul 18, 2015 · 6 comments

Comments

@tomasaschan
Copy link
Contributor

This is to discuss changes to, and completion of, documentation for this package. Major questions are:

  • How do we want to organize the documentation? Formats, locations etc...
  • What should be documented (more than just by writing clear code)? Devdocs? Implementation details?
  • On what level of detail do we want to document things?

Some discussion started in #45 already, where the following points were raised:

In a sense the README could be a summary of what's available, now that

julia> using Interpolations
julia> ?Interpolations

dumps the README contents. So I've begun to think that it might be good to keep the README as an "API reminder" for people who already understand the package, and the IJulia notebook as an introduction to the package.

I agree that it's probably a good idea to make the readme minimalistic. I'd also like to start documenting most other things in a help>-compatible way, so we might want to move off from the IJulia notebooks alltogether. And I feel like I have to strip down the LaTeX stuff to something with minimal dependencies, so anyone can at least compile it, but it is a very handy way to document the mathematical background of any methods we implement...

@tomasaschan
Copy link
Contributor Author

This was raised again in discussion in #90. I'd like to find a better place to keep documentation of math that's too lengthy and/or not relevant for docstrings.

Requirements:

  • Readable and editable in any text editor
  • It should be possible to render the equations to something nice-looking
  • It should be relatively easy to have the rendered documentation shown on the web somewhere (could be inside the repo if we choose markdown - could be something like readthedocs.org...) and update it as part of the bulid/test process.

Nice-to-haves:

  • The notation to render mathematics should, preferrably, be easy enough on the eyes to be able to follow even if looking at the plaintext version.

Any suggestions are welcome.

@tomasaschan
Copy link
Contributor Author

I asked a question on julia-users to get some input for tools and platforms: https://groups.google.com/forum/?nomobile=true#!topic/julia-users/mRk0igz_uHQ

@aramirezreyes
Copy link

I have seen in the docs some obscure infromation about how to select the behaviour outside the domain, i.e, decide wether or not to extrapolate. I haven't figured how to use it, however, i can see that ExtrapNaN or ExtrapError are no longer valid as arguments to extrapolate. I think that part of the docs could be improved. [I'll check the source and see if i can help]

@tomasaschan
Copy link
Contributor Author

That would be most appreciated!

@tomasaschan
Copy link
Contributor Author

@argelouski: I think that this section of the Readme is up to date, so that can hopefully provide some assistance, too.

@tomasaschan
Copy link
Contributor Author

This blog post should definitely be considered, too: http://maurow.bitbucket.org/notes/documenting-a-julia-package.html

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

No branches or pull requests

2 participants