Re: [pyxl] Documentation

[Chris Withers]

Hi Pete,

Welcome on board and I'm sorry you've taken my comments on
https://github.com/python-excel/xlwt/issues/28#issuecomment-18329254 the
wrong way...

On 23/05/2013 00:32, Peter 'mash' Morgan wrote:
> I;m kinda starting with the writer.. and with a tip from Chris..
> have a basic updated version here..
> https://python-excel-manual.readthedocs.org/en/latest/
> https://xlwt.readthedocs.org/en/latest/

I've asked Pete to take these down until they're ready. When they're
ready they'll appear on python-excel.org...

> So ideally what we want is cool docs for all three modules/packages ie
> (not I am referring to a module as also a git submodule)
> * xlwt
> * xlwr
> * xlutils
> * tutorial..

Indeed. Thinking about this more, the tutorial is not the best place to
start since it's in the best shape of all the packages. The best place
to help would be the xlwt API docs, which are worst of all. Have a look
at the xlutils repo and Sphinx autodoc. If we can get something similar
set up to cover the API for xlwt, that would be awesome :-)

> 1) I want to nuke the odf and pdf.. BUT we can autogen the pdf, so we
> wont loose things

Yeah, but as I said, it's in the best shape of the lot right now, so no
need to nuke...

> 2) are we tied to simpistix ..

What do you mean?

> 3) what Is the license ? ama bit consused here.. its creative comons.. ?
> is it GPL also ???

The tutorial is under
http://creativecommons.org/licenses/by-nc-nd/2.0/uk/ which technically
means your readthedocs fork is violating the license. Once we get xlwt
and then xlrd api docs over the Sphinx and sorted I'll have a re-think
of that...

cheers,

Chris

--
Simplistix - Content Management, Batch Processing & Python Consulting
- http://www.simplistix.co.uk

[Chris Withers]

Pete,

On 25/05/2013 01:17, Peter Morgan wrote:
> On 24 May 2013 18:23, Chris Withers <ch...@simplistix.co.uk

> <mailto:ch...@simplistix.co.uk>> wrote:
>
> Hi Pete,
>
> Welcome on board and I'm sorry you've taken my comments on

> https://github.com/python-__excel/xlwt/issues/28#__issuecomment-18329254

> <https://github.com/python-excel/xlwt/issues/28#issuecomment-18329254>
> the wrong way...
>

> What pissed me off is that there was no feedback upon. the DOCS .. which
> is the MAIN PURPOSE..

The appropriate way to elicit feedback on your docs work would have been
to mail this list or the project maintainers with the location of your
Sphinx source and let us go build it to take a look.

> were talking about interlinking the whole lot..

That's the thing that needs doing once the docs for the individual
packages are done. xlutils is there:

http://pythonhosted.org/xlutils/

However, xlrd needs work on this branch:

https://github.com/python-excel/xlrd/tree/docs

And, much more so, xlwt needs work on this branch:

https://github.com/python-excel/xlwt/tree/docs

Once those branches are ready, we can merge into master and publish to
pythonhosted.org. Once that's done, we can think about whether to keep
the tutorial separate or split it into chunks and merge it into package
docs.

[Peter Morgan]

Hi all,

I'm hacking away at docs, mainly because of this project..

https://github.com/daffodil/PyQtSpreadsheet

Which is a mix of day job and night job ;-)

The day job is excel everywhere on wind machines..

So I started to look at the situation and converting some stuff to rst and making it better somewhat..

This kinda stuff is quite easy I find.. What I generally want its some clickable html..

Now the position I am looking "at it" what I would want as an end developer..ie me..

And what I would want python-excel.org to be is a bit of a h(e)aven for python and excel..

After all one can go around the houses on search of things, and reading some

pdf here and another things there.. but I ended up at python-excel..

So for documentation.. 

The tool were using for this is sphinx and rst.. which are pedantic and stubborn in their own ways..

and as chris pointed out, were using pythonhosted.org/*/ as the "front end" for each project..

but sphinx is building it for us..

Quick Question, ?? is that automated from source or and acutal release "manual" process (i suspect the later)

So can I make some suggestions and some feedback et all.. this is off the top of my head ...... 

== End goal ==

1) my goal is to make the manual cool and clickable inbetween all of them.. but also we can end in a world of confusion..

   eg clcking on a xutils link end me up in the the xlrd and i dont know it cos they all look the same with sphonx..

  So the way I try to solve that is at least to have a "template" with some navigation on top..

  and also maybe some "different color" for each module.. and this is easy..

== Build DOcs ==

2) out build system = sphinx * 2

The problem..

To interlink sites and make external references, there needs to be and object.inv in each "build" of the docs..

This leads to the problem of one dependancy.. eg "the new function" or alike in one lib accecing another..

eg

intersphinx_mapping = {

    'xlutils': ('http://pythonhosted.org/xlutils/', None),

    #'xlwt': ('http://pythonhosted.org/xlwt/', None),

    'python': ('http://docs.python.org/', None),

}

Sphinx makes this bindings at compile time, so the process needs to be run twice..

      1) make build of each "project" and create objects.inv for each project, but fails in chicken and egg

      2) run second time against previous builds and chicken wins..  ;-)

So these "object.inv" are aqquired from remote server at compile.. (ie cached.. even.. ummm!!)

=== Doc Branches ========

3) branches

is there a way to bring or create "docs" branches up to date..

If a project not have docs branch, then can we create on and keep it up to date..

This is real useful for things such as explains and correcitions and even other langs later ;-)

By this I mean that they exist or reflect "head" somewhat..

The merge for example from xlrd.master to xlrd.docs is not something I think I am comfortable dealing with..

It its  huge patch upon __init__ file so this I think is best left to upstream..instead of a new  fail == stall

== Doc Patches =============

4) The docs patches..

The sphinx uses autodoc, which is a new addition and is capable of creating docs from source code and a "python" module..

so this means that there needs to be a file that represents the module to be documented..

This also means that each "function" and "attribute" in the python source that has been crafted over a few years..

is suddenly mashed up by a stranger who comes in and changes all teh comments into something else in the wrong place..

Is the main problem..

and sphinx is another cos its pretty "fussy" about things, eg a new line is required

.. note:: 

       This fails beacause no line break above..

When all one wanted was

.. note::  This works at last

instead

.. note:: 

       This workz.. stuff u sphinx and rst sometimes..

So I understand this frustrations as a documentor over the years.. but at least its not docbook ;-)))))))))))

Doxygen is current favourite, but sphinx is for pytohn only.. kinda in my heart

So this pisses devs off when lots of white space and like, just to make docs cool.. etc..

===== Config Vars ==========

The issue I want to raise is where is the __version__ and __author__ and __license data etc..

its all over the place..

But what works is probably whats in the source..

For example,, the sources of xlrd have the .info module with verion

What I would expect is a file similar to this..

https://github.com/z4r/python-rtkit/blob/master/rtkit/__init__.py

But theragain I am a new kid on the block..

How they are being used is that sphhinx loads stuff uponn config from project..

so the variables need to be there..

eg

https://github.com/pedromorgan/xlrd/blob/docs/doc/source/conf.py#L25

And then the __version __ is proper down the line..

The same goes for authors and license and desription et all..

=== Main requests ===

* can someone create the "doc" branches and up to date in code and can patch to that..

suggest to use use "doc/" as the directory as this is what pypi recommend in install..

* What are the developer guidelines for helping with documentation

Pete

[Werner]

Hi Peter,

On 28/05/2013 03:28, Peter Morgan wrote:

...

Just an FYI

The wxPython Phoenix project is using Sphinx to do the new
documentation, there might be some things to pick up from there.

I really like that the search box in the header is always visible, makes
it a lot easier to find things.

http://wxpython.org/Phoenix/docs/html/index.html

http://wxpython.org/Phoenix/docs/html/DocstringsGuidelines.html

A lot of this is extracted from the C++ wxWidgets doc and "massaged",
but everything in wx.lib is extracted from the Python doc strings.

Werner

[Chris Withers]

On 28/05/2013 02:28, Peter Morgan wrote:
> <http://pythonhosted.org/*/> as the "front end" for each project..

> but sphinx is building it for us..
> Quick Question, ?? is that automated from source or and acutal release
> "manual" process (i suspect the later)

Is what automated?

> == End goal ==
> 1) my goal is to make the manual cool and clickable inbetween all of
> them.. but also we can end in a world of confusion..

I hate to be blunt, but this isn't that important. Getting the xlrd docs
ported to Sphinx and/or writing xlwt docs *are* important, just not as
sexy...

> eg clcking on a xutils link end me up in the the xlrd and i dont
> know it cos they all look the same with sphonx..

For someone keen on writing docs, the content of your emails is
extremely sloppy...

> === Doc Branches ========
> 3) branches
> is there a way to bring or create "docs" branches up to date..
> If a project not have docs branch, then can we create on and keep it up
> to date..

xlutils docs are done. xlrd and xlutils both have docs branches. Both
could likely benefit from being rebased on master.

> This is real useful for things such as explains and correcitions and
> even other langs later ;-)

Will we have to make corrections to your correcitions? ;-)

> ===== Config Vars ==========
> The issue I want to raise is where is the __version__

xlrd.info

>and __author__

setup.py

> and
> __license data etc..

xlrd.licenses.

All of which are easy to find if you look at the source, which I would
imagine would be important if you're planning on writing docs...

> suggest to use use "doc/" as the directory as this is what pypi
> recommend in install..

Where are the recommendations you're referring to?

[Peter Morgan]

My regected patch fullfils the "rst and docs created"

I dont understand anymore..

So u want to me make each comment and RST style docs changes as an atomic patch..

That is why u get the full patch..

I suspect if u deal with __init__ then cool

But regardless of that a lot of the "olde style comment are now rst..

Anyway am real diappointed, as chris never even compiled or anyone else..

So the goal of pyxl at the moment is..

1) reject any patch unless I can se in gitbub, and decide its to far..

2) send muppet message to day.. yes u did not do things rights and message is negative..delete patch..

3) in the meantime everyone is waiting and wanting the new docs so they can join in without the hassle of a megga pdf download

So in fact it was never checkout out..

That is real disappointing.. That is evaluation of code on a look, and nto reality..

If that is your patch technique then I suspect the shole project is in doubt.. 

and will become even more stagnants..

So u have to checkout my docs patch and maybe use meld or alike and compile the docs..

Please complain back to me if it doth not compile.. immedeately... 

Ta

Pete ;-)

--
You received this message because you are subscribed to the Google Groups "python-excel" group.
To unsubscribe from this group and stop receiving emails from it, send an email to python-excel+unsubscribe@googlegroups.com.
To post to this group, send an email to python...@googlegroups.com.
Visit this group at http://groups.google.com/group/python-excel?hl=en-GB.
For more options, visit https://groups.google.com/groups/opt_out.

[Chris Withers]

On 01/06/2013 04:01, Peter Morgan wrote:
> My regected patch fullfils the "rst and docs created"
>
> I dont understand anymore..
>
> So u want to me make

I have no idea who you're replying to,, but anyway...

> each comment and RST style docs changes as an
> atomic patch..

No, it's just impossible to review a pull request where there's one
monster commit that contains both a branch merge and a set of
documentation changes. At the very least, do those two things as two
commits.

> I suspect if u deal with __init__ then cool
> But regardless of that a lot of the "olde style comment are now rst..
>
> Anyway am real diappointed, as chris never even compiled or anyone else..

Pete, I'll say this once again, for someone who want to work on
documentation, the structure of your emails is appalling, put the effort
in to write emails in the same way you intend to write docs and people
might take you a bit more seriously, vomit forth barely coherent
missives full of sms-speak and you're likely to be ignored very quickly.

> 3) in the meantime everyone is waiting and wanting the new docs so they
> can join in without the hassle of a megga pdf download

No had anyone else complain about PDF, so be careful about what you're
basing your assumptions on.

> So in fact it was never checkout out..

By "it" I'll assume you mean your pull request, in which case, yes, I
did review it, looks like Thomas did to, and we both had the same concerns.

[Werner]

Hi Peter,

Instead that you expect Chris or whoever to apply your changes, then try
to build and and and.

I would suggest that you build your version of the docs and put them up
on some server so people can have a look on what they look like. That
worked for Andrea (who proposed and now does the wxPython doc) it worked
for me when I suggested such a move for Dabo (the Dabo team then took it
over and maintain it).

Just my 0.02�

Werner

[Chris Withers]

Hi Werner,

On 01/06/2013 08:49, Werner wrote:
> I would suggest that you build your version of the docs and put them up
> on some server so people can have a look on what they look like. That
> worked for Andrea (who proposed and now does the wxPython doc) it worked
> for me when I suggested such a move for Dabo (the Dabo team then took it
> over and maintain it).

Pete actually did this and I asked him to take them down.

I have very real concerns about a half-finished docs project being left
lying around and confusing new users who might mistake it for the right
place to be looking for something.

For me, the best thing to do would be to do the work on a branch in a
fork on GitHub that anyone interested can check out and build.

I have no problem with that, but so far Pete's submissions have been
confused and confusing, much like his emails. I can only assume he's
relatively young and I'm trying to direct his well-meaning energies in
the right direction...