Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.debian.maint.python > #9929 > unrolled thread

doc-central

Back to article view | Back to linux.debian.maint.python

Contents

  doc-central Diane Trout <diane@ghic.org> - 2017-10-13 00:10 +0200
    Re: doc-central Diane Trout <diane@ghic.org> - 2017-10-13 00:40 +0200
      Re: doc-central Paul Wise <pabs@debian.org> - 2017-10-13 02:20 +0200
        Re: doc-central Simon McVittie <smcv@debian.org> - 2017-10-13 09:50 +0200
          Re: doc-central Diane Trout <diane@ghic.org> - 2017-10-13 19:40 +0200
    Re: doc-central Stuart Prescott <stuart@debian.org> - 2017-10-13 01:10 +0200

#9929 — doc-central

Hi,

I wanted to be able to browse documentation locally, and the Python
viewer doc-central is abandoned.

What I have so far is a Python 3 version using CGI scripts. What I'd
like is something uses wsgi and can run with Python's built-in wsgiref
server instead of requiring a full web server. (maybe flask?)

Pending a better repository my changes are currently at:
https://github.com/detrout/doc-central

I did reformat the code according to current pep 8 conventions. (There
were so many tabs...)

Also doc-central had its own code using the long deprecated rfc822
library for reading the package doc-base files. I dumped that and used
the Deb822 reader in python3-debian.

I forgot to look for a svn repository so I built a history with gbp
import-dsc. (Though the original svn repository is also pretty small,
and lacks tags).

Anyone want to review the changes? Should I release a new version?

Does anyone have a good way of migrating the old svn repository? Is it
even necessary? Where should a new git repository go?

Diane

[toc] | [next] | [standalone]

#9930

On Thu, 2017-10-12 at 20:10 +1100, Stuart Prescott wrote:
> BTW when doc-central was first orphaned, there was a little
> discussion about 
> bringing it under the debian-doc umbrella (but there is no reason not
> to use 

That does seem reasonable. I joined the -doc list and emailed them

> d-python either given that discussion never came to anything
> concrete). 
> There was also a desire to look at rarian integration for tools like
> yelp 
> and khelpcenter for ease of document discovery. Hopefully some of the
> people 

I explored a bit after you reminded me about rarian and yelp.

It was never really obvious to me what rarian's purpose was doing from
its freedesktop site. It basically finds doc-base registered and man
pages? (Seems like the kind of thing that should have perl & python
bindings ;) )

Also it looks like none of the Debian documentation tools know about
how to read the GNOME documentation format?

Being able to find all your documentation in one place would really be
convenient.

Diane

[toc] | [prev] | [next] | [standalone]

#9934

On Fri, Oct 13, 2017 at 3:27 AM, Diane Trout wrote:

> Being able to find all your documentation in one place would really be
> convenient.

I don't think doc-base/doc-central will ever be the answer to this as
it is very specific to Debian and thus not available on other distros.
Eventually the Freedesktop folks will come up with something
cross-distro and cross-desktop and we will have to replace doc-base
with it, just like we had to do with the Debian-specific menu system.

-- 
bye,
pabs

https://wiki.debian.org/PaulWise

[toc] | [prev] | [next] | [standalone]

#9935

On Fri, 13 Oct 2017 at 08:13:08 +0800, Paul Wise wrote:
> On Fri, Oct 13, 2017 at 3:27 AM, Diane Trout wrote:
> 
> > Being able to find all your documentation in one place would really be
> > convenient.
> 
> I don't think doc-base/doc-central will ever be the answer to this as
> it is very specific to Debian and thus not available on other distros.
> Eventually the Freedesktop folks will come up with something
> cross-distro and cross-desktop and we will have to replace doc-base
> with it, just like we had to do with the Debian-specific menu system.

... unless someone from Debian with an interest in documentation goes
upstream and comes up with something cross-distro, cross-desktop and
suspiciously similar to doc-base. Relevant people to talk to would
include the maintainers of GNOME's yelp (user-facing, usually-topic-based
help in Docbook or Mallard format, processed into HTML for viewing) and
devhelp (developer reference documentation in any format, processed into
HTML at build-time), and their equivalents in other upstream projects.

As far as I understand it, yelp and devhelp are separate apps as a
deliberate design choice, because they have different audiences and
requirements. Whether you agree with it or not, understanding the
reasoning behind that design choice seems likely to be valuable.

    smcv

[toc] | [prev] | [next] | [standalone]

#9936

On Fri, 2017-10-13 at 08:41 +0100, Simon McVittie wrote:
> On Fri, 13 Oct 2017 at 08:13:08 +0800, Paul Wise wrote:
> > On Fri, Oct 13, 2017 at 3:27 AM, Diane Trout wrote:
> > 
> > > Being able to find all your documentation in one place would
> > > really be
> > > convenient.
> > 
> > I don't think doc-base/doc-central will ever be the answer to this
> > as
> > it is very specific to Debian and thus not available on other
> > distros.
> > Eventually the Freedesktop folks will come up with something
> > cross-distro and cross-desktop and we will have to replace doc-base
> > with it, just like we had to do with the Debian-specific menu
> > system.
> 
> ... unless someone from Debian with an interest in documentation goes
> upstream and comes up with something cross-distro, cross-desktop and
> suspiciously similar to doc-base. Relevant people to talk to would

FWIW rarian is the closest thing to a freedesktop documentation
standard. It derives from scrollkeeper, and I thought scroolkeeper was
originally from Debian.


> As far as I understand it, yelp and devhelp are separate apps as a
> deliberate design choice, because they have different audiences and
> requirements. Whether you agree with it or not, understanding the
> reasoning behind that design choice seems likely to be valuable.

My first guess is that separating them makes it easier to simplify
search. Users will find user docs and developers will find developer
docs, and they can't accidentally be confused.

Which makes me wonder a bit about all the sphinx docs where there's a
user chapter and then API docs.

Diane

[toc] | [prev] | [next] | [standalone]

#9933

Dear Diane,

> Pending a better repository my changes are currently at:
> https://github.com/detrout/doc-central

This is excellent news, thanks!

BTW when doc-central was first orphaned, there was a little discussion about 
bringing it under the debian-doc umbrella (but there is no reason not to use 
d-python either given that discussion never came to anything concrete). 
There was also a desire to look at rarian integration for tools like yelp 
and khelpcenter for ease of document discovery. Hopefully some of the people 
who were interested back then will re-emerge to contribute, now that you've 
laid the ground work. (I hope to do so…)

cheers
Stuart

-- 
Stuart Prescott    http://www.nanonanonano.net/   stuart@nanonanonano.net
Debian Developer   http://www.debian.org/         stuart@debian.org
GPG fingerprint    90E2 D2C1 AD14 6A1B 7EBB 891D BBC1 7EBB 1396 F2F7

[toc] | [prev] | [standalone]

Back to top | Article view | linux.debian.maint.python

csiph-web