arkouda
arkouda copied to clipboard
Bears-R-Us
enhancements to generated arkouda documentation
I have some questions about enhancing the Arkouda Documentation.
- changing to a "dark" theme (mostly selfish because of my cataract)
- including the markdown files from the repo into the generated doc
- producing a PDF version of the documentation
Maybe use https://pypi.org/project/pydoc-markdown/ to include the markdown files.
Maybe use https://pypi.org/project/pydoc-markdown/ to include the markdown files.
@mhmerrill - I believe pydoc-markdown creates the documentation in markdown format. However, it looks like there is a solution with sphinx, here.
For the "dark" theme in documentation, I am not sure about actually writing the docs at https://bears-r-us.github.io/arkouda/ out with a dark theme. However, for a quick fix, Dark Reader is an excellent browser extension that allows you to always use a dark theme, or only use it on specific websites. It is very easy to turn on and off as well. Here is a link, Dark Reader.
It also looks like Sphinx has themes that you can apply. Some information is available here https://www.sphinx-doc.org/en/master/usage/theming.html.
It should not be difficult to convert the documentation to PDF. I have done it in the past with tools like pdfkit. This will allow you to take the HTML output and save it as a pdf.
@Ethan-DeBandi99 I don't have the ability to install anything in the organizationally managed version of Chrome ;-( although most things have a dark theme or mode...
Adding some notes after messing around with a dark theme for documentation.
pip install groundwork-sphinx-theme
Then, pydoc/conf.py can be updated with html_theme = 'groundwork'.
groundwork is one of the only (if not the only) ready made "dark" themes for sphinx. I ran make doc with this setup, but certain things can be more difficult to read. After doing a bit more research, it should be fairly simple to generate our own custom styling for our documentation.
While doing this, I also noticed that a lot of the documentation that is generated by make doc (most the startup/dependencies stuff) is extremely outdated and should be updated. I will be adding issues to look into handling both of these things.
PR #1981 adds a dark theme and includes the markdown files.
I am still looking into generating a PDF, but I am not sure that it gets us much
Quick search of Sphinx documentation looks like they recommend rinohtype for direct PDF creation, but that only support rst formatting so we would not be able to include our markdown files, which would be a problem.
Sphinx supports generating Latex source files that can be used to generate PDFs, but it requires an extra step. This method looks like we would be able to include markdown files though.
@pierce314159, @joshmarshall1 , @jaketrookman, @hokiegeek2 - do you think we need to have PDF formatted documentation? I am not convinced it will provide anything we don't already have.
@pierce314159, @joshmarshall1 , @jaketrookman, @hokiegeek2 - do you think we need to have PDF formatted documentation? I am not convinced it will provide anything we don't already have.
i don't see any need to produce a pdf. As far as i know, all our users have access to our github pages documentation
