Meta info about i2mint organization and projects
i2mint / epythet Goto Github PK
View Code? Open in Web Editor NEWTools for documentation
Home Page: https://i2mint.github.io/epythet/
License: Apache License 2.0
Tools for documentation
Home Page: https://i2mint.github.io/epythet/
License: Apache License 2.0
I would be nice for the user to be able to know what version the documentation pertains to, and view earlier versions as well (like python or sklearn docs do).
It's also nice for the developer to know when the docs were generated (for example, to see if a new generation came through yet). Unless a better/easier idea comes along; generation date should be included subtly (small font, gray, footer?).
Sphinx does this with rst: https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html
How do we get this to work with md?
For the documentation to be published, you need to got to https://github.com/i2mint/unbox/settings/pages, then do some simple manipulations, like:
Simple, yes, and usually only has to be done once. Still, having it done automatically would be nice if it's not too much dev to get there. Is there an API or a CI instruction that would get us there?
See: https://github.com/i2mint/stream2py/blob/master/stream2py/examples/usage/triggered_starts.py
Also, how do we graphviz with markdown.
I see that epythet imports recommonmark, but as seen on recommonmark's page it is now deprecated in favor of MyST:
"Warning: recommonmark is now deprecated. We recommend using MyST for a docutils bridge going forward. See this issue for background and discussion.": recommonmark deprecated
The presence of local docs produces a lot of annoying "information washout":
When searching for objects, a big proportion of files are html or js, which makes it hard to find stuff.
The cleaner solution would be that I parametrize the search to ignore .js and .html files, but haven't managed to find how to do that.
Hard to see what’s (arguably) more important when, say, doing a git pull.
Of course, it's nice to have local documentation, but personally I almost always use online documentation, so it's an easy price for me to pay to not have the docs locally.
What about the solution of putting docs/*
in the gitignore. Would that be sufficient? in which situations would that not be recommended?
I've seen some html documentation have a "toggle >>>" button that allows the reader to switch from
>>> t = 3 + 2
>>> t
5
view to a
t = 3 + 2
t
view that's easier to copy/paste/try.
How do we integrate this option in epythet's doc gen?
I've disabled the markdown support because it messes with the rst code blocks and numbered lists. You can find examples on this page when you compile the docs:
https://i2mint.github.io/epythet/module_docs/epythet.html
This code needs to change
epythet/_static/docsrc/conf.py
import commonmark
def docstring(app, what, name, obj, options, lines):
md = '\n'.join(lines)
ast = commonmark.Parser().parse(md)
rst = commonmark.ReStructuredTextRenderer().render(ast)
lines.clear()
lines += rst.splitlines()
def setup(app):
app.connect('autodoc-process-docstring', docstring)
The markdown parser should not be blindly applied to the entire document.
One possible solution is to have some kind of sentinel or keyword show where md starts and finishes and only apply it to those sections. Even better if you can tell the difference between md and rst without the users knowledge.
Documentation must be added for whatever the solution ends up being.
Another problem to solve in doc gen: Spell checking.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.