Comments (12)
@kernc If you give me some pointers I'll happily write up a PR.
from pdoc.
+1
from pdoc.
Which README.md would that be, the one in the same directory as __init__.py or one upper?
Only README.md or also readme.md, README.txt, README.rst?
from pdoc.
The way it would yield the most is with reST .. include::
directive.
How do you feel about that?
from pdoc.
If anyone would have a stab at that, the code is here.
There's already an exception for .. image::
and .. figure::
.
Lines 189 to 215 in e2739ce
from pdoc.
From the user's perspective, I was thinking of using it like:
pdoc mymodule --html --inject-markdown-to-index=/PATH/TO/MY/README.md
from pdoc.
I think that's too ambiguous. Every package with __init__.py has an index. Which index?
Then, you can't control whether the injection is appended to or replaces the existing docstring.
Do you particularly dislike the .. include::
approach?
from pdoc.
I'm in favor of the .. include::
approach. Seems easy enough while allowing a lot more flexibility.
On a different page, what is rendered as index when I make pdoc
build multiple modules?
from pdoc.
.. include::
is definitely good! Flexibility is great.
I was just mentioning an alternative user interface in my previous comment.
from pdoc.
from pdoc.
- Make another admonition
type
exception for'include'
(probably call another function if more than a couple of lines).- Open up a file, read and return its contents but with each line preceded by
indent
.- If the file doesn't exist, re-raise a more descriptive exception.
- Relative paths should probably be relative to the include statement appearance. You will need to pass
module
to_ToMarkdown.admonitions()
to be able to handle relative includes. - I don't think you need to worry about directive options (
:start-line:
,:end-line:
, ...) that you would find intext
. Unless you find them trivial to implement, I'm completely happy if we don't support them or maybe add them later on an as-needed basis.
- Open up a file, read and return its contents but with each line preceded by
- Add a documentation subsection "Supported reST directives", describing in brief what directives are supported and how.
from pdoc.
I wrote up everything as described (including the start end stuff) in PR #16 .
from pdoc.
Related Issues (20)
- Upgrade code reference warnings to errors. HOT 1
- --skip-errors flag does not work
- feature request: support for headings to organize functions
- Include html containing javascript
- Using a - in folder names prevents linking
- missing docstrings of methods HOT 3
- syntax error with match-case function HOT 1
- Incorrectly rendered Args section HOT 1
- Add GitHub Flavor Markdown support HOT 2
- Remove indentation in text template for markdown files HOT 1
- Deprecation warning for PEP224 class variable docstrings
- "x | y" does not work but "Union[x, y]" does HOT 4
- pdoc3 0.11.0 installation regression vs 0.10.0. HOT 3
- version 0.11 is not compatible with python 3.7 HOT 2
- Search function HOT 3
- Links not generated in Markdown tables HOT 1
- Cannot get search to work HOT 2
- Make it possible to ignore class members based on wildcard strings HOT 1
- setting `git_link_template` causes failures on `property` and `cached_property`
- submodule containing a function or class of the same name as the submodule won't be identified
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from pdoc.