keras-team / keras-autodoc Goto Github PK
View Code? Open in Web Editor NEWDocumentation autogeneration utilities.
License: Apache License 2.0
Documentation autogeneration utilities.
License: Apache License 2.0
Seeing this for example with kerastuner.Tuner.run_trial
Hi @gabrieldemarmiesse , is there a way to have a class documentation use its alias rather than its actual class name?
I.e. we have keratuner.tuners.randomsearch.RandomSearchOracle
but we also have this aliased as kerastuner.oracles.RandomSearch
. Is there a way to make the second name be the display name in documentation?
The readme is practically empty and we should have a small doc website with a simple tutorial.
The functions to document are:
autogen.DocumentationGenerator
, autogen.get_classes
, autogen.get_functions
, autogen.get_methods
.
To get started, you can mimic this https://github.com/keras-team/keras-tuner/tree/master/docs
Currently Keras Autodoc appends the word "class" to the names of classes in their docs headers (example in our Larq docs, larq.layers.QuantDense
becomes "QuantDense class") and "function" to the names of functions (example).
We think this adds a bit of unnecessary visual noise/clutter (see larq/docs#118), so I was wondering if this is something we can make optional or remove altogether? I'd be happy to make a PR myself, just wanted to check in before I do. :)
Currently the link [Source]
is only displayed for classes. It would be nice to display it with classes and functions. It shouldn't be too hard.
Args
is it possible to extend the if comparison by Args
, too?
According to https://google.github.io/styleguide/pyguide.html to use Args
instead of Arguments
is valid as well as official proposed and allows to be consistent with other packages, too.
keras-autodoc/keras_autodoc/docstring.py
Line 73 in 0d7d1cd
if section_title == "Arguments" or section_title == "Args":
Hi,
I'm using this package for documenting all my Python packages, especially this one.
It worked very well on my last commit but now, when I run python3 docs/autogen.py
, I get the following error messages:
Traceback (most recent call last):
File "docs/autogen.py", line 4, in <module>
import keras_autodoc
File "/Users/t/Documents/Python_Packages/teller/venv/lib/python3.8/site-packages/keras_autodoc/__init__.py", line 1, in <module>
from .autogen import DocumentationGenerator
File "/Users/t/Documents/Python_Packages/teller/venv/lib/python3.8/site-packages/keras_autodoc/autogen.py", line 8, in <module>
from .get_signatures import get_signature
File "/Users/t/Documents/Python_Packages/teller/venv/lib/python3.8/site-packages/keras_autodoc/get_signatures.py", line 5, in <module>
from sphinx.util.inspect import Signature
ImportError: cannot import name 'Signature' from 'sphinx.util.inspect' (/Users/t/Documents/Python_Packages/teller/venv/lib/python3.8/site-packages/sphinx/util/inspect.py)
It seems like the problem comes from this file, and a change in Sphinx's API. Could you please help me in solving this issue?
@gabrieldemarmiesse Thanks for fixing the previous issues so quickly!
It would be a great feature if we had a way to mark code snippets that exist in the documentation in a way that indicates that they should be run as tests. During python autogen.py
, we could extract those snippets into tests that can be run with pytest. This way we could ensure our examples stay up-to-date
See discussion on keras-team/keras-tuner#136 (comment), we would probably have to roll our own solution for this
I am completely new to python and mkdocs, so I started a pet project for testing purposes and I wanted to use keras-autodoc
for documenting my own functions (looks really promising, and I can use markdown instead of rst).
If I am not wrong, after configuring autogen.py
and running mkdocs serve
a new .md
file will be created with the documentation of all functions listed within the pages
variable.
After reading readme.md
file, I tried to adapt it to my project, but without success.
My project uses the following structure:
├── docs/ <- where mkdocs and autogen.py are located.
├── src <- Source code for use in this project.
│ ├── __init__.py <- Makes src a Python module
│ ├── features <- Scripts to turn raw data into features for modeling
│ ├── __init__.py
│ └── bcn_trees.py
You can see the complete repo here
With that structure, I created a docs/autogen.py
file with the following content:
# content of docs/autogen.py
from keras_autodoc import DocumentationGenerator
pages = {
'api_bcn_trees.md': [
'bcn_trees.data_download',
'bcn_trees.data_munging']
}
doc_generator = DocumentationGenerator(pages)
doc_generator.generate('./sources')
but when running mkdocs serve
the api_bcn_trees.md
file is not generated. What am I doing wrong?
I'm seeing an issue where if a docstring exists in the super class but not in the subclass method then it is not showing up at all
In particular wrapping a function with @contextlib.contextmanager
is making it so that the arguments don't show up
Having this issue with kerastuner.HyperParameters.conditional_scope
When having an enum as a default parameter in any function, the following error occurs:
black.InvalidInput: Cannot parse: 1:72: def xxxx(metric_type=<COCOMetricType.bbox: 'bbox'>, print_summary=False):
The error tells everything, inside format_signature
black is used and it cannot understand <Classname...>
because that's not valid python code.
I've found two workarounds but they are both suboptimal. The first is to use None
in the default value instead, and the second, to change the enum __repr__
/__str__
.
Is there another way to get around this error? I can try drafting a PR if you think this is easily solvable.
It would be nice to have support for argparse
for command line scripts.
Hi!
In setup.py
black is pinned to the version 19.10b0
, is that a hard requirement for the documentation to build properly?
I'm using your package as a dependency of mine, and this also requires me to lock the version of black, I tested building the docs with the newest version of black and it seemed to work just fine.
Displaying them in the signature is too heavy. It's better fitted in the description. Same for the return type.
See keras-team/autokeras#957 (comment)
Overall, this is more a general issue with the https://github.com/keras-team/keras-autodoc/blob/master/keras_autodoc/docstring.py file. It's overly complicated. Some refactoring would be welcomed.
At the same time, if the code is simpler, it should be easier to fix the test currently failing:
keras-autodoc/tests/test_docstring.py
Line 99 in e94388e
When parsing a @dataclass
, DocumentationGenerator.generate
fails with AttributeError: module 'mantisshrimp.core.bbox' has no attribute '__create_fn__'
(full stack trace at the bottom).
What happens is that the __init__
representation from dataclasses is different than for normal classes.
For normal classes we have:
<function DocumentationGenerator.__init__ at 0x104e56710>
While for dataclasses:
<function __create_fn__.<locals>.__init__ at 0x13b3c1290>
If I understood the problem correctly, get_class_from_method
is trying to get the name of the class from the representation, but the name of the class is not present in the dataclass __init__
.
Traceback (most recent call last):
File "autogen.py", line 340, in <module>
generate(mantisshrimp_dir / "docs" / "sources")
File "autogen.py", line 256, in generate
doc_generator.generate(dest_dir)
File "/Users/lgvaz/anaconda3/envs/mantis/lib/python3.7/site-packages/keras_autodoc/autogen.py", line 82, in generate
markdown_text += self._render(element)
File "/Users/lgvaz/anaconda3/envs/mantis/lib/python3.7/site-packages/keras_autodoc/autogen.py", line 109, in _render
return self._render_from_object(object_, signature_override)
File "/Users/lgvaz/anaconda3/envs/mantis/lib/python3.7/site-packages/keras_autodoc/autogen.py", line 116, in _render_from_object
object_, signature_override, self.max_signature_line_length
File "/Users/lgvaz/anaconda3/envs/mantis/lib/python3.7/site-packages/keras_autodoc/get_signatures.py", line 51, in get_signature
return get_class_signature(object_, override, max_line_length)
File "/Users/lgvaz/anaconda3/envs/mantis/lib/python3.7/site-packages/keras_autodoc/get_signatures.py", line 45, in get_class_signature
signature_end = get_signature_end(cls.__init__)
File "/Users/lgvaz/anaconda3/envs/mantis/lib/python3.7/site-packages/keras_autodoc/get_signatures.py", line 25, in get_signature_end
if utils.ismethod(function):
File "/Users/lgvaz/anaconda3/envs/mantis/lib/python3.7/site-packages/keras_autodoc/utils.py", line 80, in ismethod
return get_class_from_method(function) is not None
File "/Users/lgvaz/anaconda3/envs/mantis/lib/python3.7/site-packages/keras_autodoc/utils.py", line 73, in get_class_from_method
meth.__qualname__.split('.<locals>', 1)[0].rsplit('.', 1)[0])
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.