Ka-Ping Yee wrote: > > ... > > I'd like Python to come packaged in such a way that people can > easily deploy it in an organization along with whatever stuff > they develop. So being able to very easily generate and see docs > on their own modules, integrated with the view of docs for the > rest of the standard library, would be a nice thing. It makes a > Python environment easier to support. Agreed. I'm just not sure if it requires a webserver. You could set up a makefile to recognize when an HTML doc is out of sync with its Python. > The way i imagined it, it wouldn't depend on htmldoc or the web > server at all. It would call inspect.py to get its info and just > format some text on its own. I didn't know about the clean separation of htmldoc and inspect when I wrote that. You're right, it should call inspect directly. > This is basically identical to how you were describing the > onlinehelp/help commands. I didn't think of using the external > (TeX/HTML) documentation though... that's a clever idea. So: > > - use doc pages only? That's not doable unless there is a process to get docstrings into doc pages -- which is a great idea but probably some ways away. > - use internal info only? Where do I get information on statements and "topics" (like slicing, as a topic). > - separate scripts for each? Maybe internally. Ideally not at the user interface layer. > - use doc pages if installed, then fall back to internal info? My model, which you may or may not have noticed yet, is to use docstrings for objects that have docstrings, but the docstrings can point to HTML documentation in the circumstance where the canonical doc is maintained in HTML. In that case, I magically go to the HTML, rather than showing the reference. My personal feeling is that over time a lot of the library documentation should move inline for ease of maintenance and reduction of duplication. But that won't happen until we integrate inspect.py and latex2html. I have some ideas about that too. It's the opposite of the current scheme. We should put pointers from the LaTeX into the modules. A preprocessor would use inspect.py to generate a combined LaTeX that merges inline (LaTeX) and out-of-line (docstring) information. Then we start moving bits of the documentation into docstrings a little at a time. Anything that uses LaTeX features that are "funky" can stay in LaTeX until we invent a structured docstring syntax (whenever). > One other note: how about leaving the job of listing the text to > to an external app like "less"/"more", as determined by the PAGER > environment variable, allowing customization? The code we use to > figure out what program to run should eventually move into > launch.textviewer. I'm happy to do this on platforms that support it. I'm somewhat nervous about popen on non-Unix systems...maybe I should write a text file and then launch the pager on that. > Perhaps this would then provide interactive apps (e.g. IDLE) the > opportunity to simply replace (or hook into) launch.textviewer. Good idea. One tricky issue is what format to use, though. troff/man is great for Unix TTY, HTML is great for GUIs and raw text is the lowest common denominiator. Do I want to get into n*m translations? Maybe, maybe not. Or maybe HTML is the lowest common denominator and Unix TTY users should use lynx? -- Paul Prescod - Not encumbered by corporate consensus It's difficult to extract sense from strings, but they're the only communication coin we can count on. - http://www.cs.yale.edu/~perlis-alan/quotes.html
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4