-
Notifications
You must be signed in to change notification settings - Fork 18
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
Added Read the Docs support #100
Comments
This issue can be closed anytime, as it has already been resolved. It was more of an announcement. |
Great, thanks @jordiferrero for starting out on this. I have been wanting to suggest this for a while as well. Now that the basic setup is done, it should be straightforward to contribute. I would propose that I redirect the domain https://lumispy.org to the documentation then. Given our logo, we should maybe use a dark theme as standard. For example that is possible with the theme used by https://kikuchipy.org (though the background behind the logo is not completely black there). |
See #103 |
ToDo:
|
How did you get a All ToDo's I completely agree and we are getting started in Cambridge to cover some of those initial documentation files. One last comment I had was whether to use |
Reserved it about a year ago on private account (costs only 18 Euro a year). So far, it points to the GitHub page.
Feel free to add points to the list! Just thought it would be good to document the process/progress. If we add the associated PRs to the end of the points, we can also document who is working on what.
I can live with both. But converting some file types yesterday, I agree that |
I don't know, but I would expect |
Here is some reading on MarkDown vs ReStructuredText: Seems that markdown is definitely more limited. In particular when it comes to e.g. math in the documentation (which we will have). Note that also the docstrings are in ReST and using different languages there makes little sense. As ReST is the standard in python documentation and used in related projects such as HyperSpy, I would stick to it. What we could do, is to use the markdown extension for sphinx (https://www.sphinx-doc.org/en/master/usage/markdown.html) and then individual pages, such as the ones residing in the main folder can remain in MD. |
The Furo theme is light (default) or dark depending on the request by the user's browser. We use default Furo without customization in kikuchipy. Note that some care must be taken with Matplotlib figures as backgrounds should be explicitly set to white so that axes labels and such are readable in the dark theme. HyperSpy's
If I remember correctly, it was as simple as pointing to it via the Read the Docs admin pages.
As with most development choices in kikuchipy (testing, documentation, CI, and so on), including the choice of .rst for non-user-guide pages (user guides are Jupyter Notebooks run and converted with nbsphinx), kikuchipy follows in HyperSpy's footsteps. I've no experience with converting other than from ReST to MD for the changelog using pandoc. |
@jordiferrero can you add the domain on readthedocs as described in this link? I would then set up the pointer on the provider side. |
Thanks @hakonanes for the feedback and advice. I really like the Furo theme as well, but given that our logo's background is black (and I really prefer that version over the white one), the best solution to me was to adapt the theme from Pillow to have a black background behind the logo both in the dark and light version. But thanks for the comments for possible caveats of the documentation in dark theme. |
@jordiferrero, we should discuss whether we should integrate the demos into the user guide. I basically see three options,
|
Two comments:
Happy to discuss further! |
I strongly agree with this. The risk with using notebook is that it is very easy to have too much code and not enough explanation, which means that the section is more a demo than a tutorial or a user guide. |
At the moment lumispy.org points to the lumispy.readthedocs.org - but with the settings described here, we should be able to make it work so that it looks as if you stay on lumispy.org |
Sorry for the delay.
I do not have access to the domain website, so I need you help :-) |
I'm checking with the provider how to set that up, seems that they may have to edit the entry. |
Aargh, the provider does not support ANAME or ALIAS (apparently a proprietary, non-standard add-on to DNS). Only possibility apart from migrating the domain seems to be setting a CNAME record for |
Would it be possible to get |
It is all working now with |
The following points were still remaining on the checklist:
|
As you had been at it already with #141, and both installation pages are from you -- could you have a look at the installation guides again @jordiferrero? For the fitting and variance documentation, would that be something for you @LMSC-NTappy? |
Thanks for the nice work @jlaehne ! For me it looks good, I don't think much more than this is needed in the fitting and variance documentation. I know it will sound like an attempt at self promotion (which it is), but do you think it could be beneficial to add a reference to my article covering the topic as well? Feel free to refuse :) |
There is the additional page on fitting in general, which is still a stub: https://docs.lumispy.org/en/latest/user_guide/fitting_luminescence.html |
Fair enough, I will expend the doc on fitting when I find time and cite my paper (Indeed, I did not make use of lumispy then). Sorry it might take a few month before I am able to find time to do it, as I am currently writing my dissertation =]. Cheers Nicolas |
@Attolight-NTappy, could you have another look at https://docs.lumispy.org/en/latest/user_guide/fitting_luminescence.html#signal-variance-noise and maybe add a small paragraph on the variance. Last thing on the list of this issue. |
Hi all,
I have wanted to do this for very long...
I have now added support for the read the docs. This means that we can have explanations on the functions we write/methodologies in a nice formatted way.
As far as I am aware, such guides can be added to
user_guide/file.rst
. Feel free to add content there.I have a list of pages I would like to add for the analysis of PL data (coming soon).
@jlaehne Maybe you could take care on the Jacobian transform documentation if you feel like explaining in a bit more detail how LumiSpy does this transform. That'd be a great opportunity to test it out too.
I believe having this will help external users to get started, as a nicely explained guide (like the EDX analysis page in HyperSpy docs) can really become "the place to check" on how to do data analysis of a particular data signal. I think the demo notebooks are great, but they can also get a bit messy.
Happy to hear suggestions!
PS: The Read the docs should trigger a build every time there is a merge. It will loop though all the docstrings and update the docs automatically.
The text was updated successfully, but these errors were encountered: