On 20/08/2013 16:07, William H. Magill wrote:
On Aug 20, 2013, at 5:15 AM, "Dr. Trigon" dr.trigon@surfeu.ch wrote:
What about a README file instead of an URL? Was there a final decision made whether to docu things locally in the repo (REDAME, doxygen, ...) vs. online www.mediawiki.org ?
The README file for pywikipedia IS A BLOODY JOKE!!!!
It provides ZERO information.
That point technically isn't true (it gives a sentence long description of what Pywikipediabot is), but I get what you're saying. It's not very helpful at all and we should change this. How, I'm not entirely sure, because as CONTENTS says, its a description for use with the nightlies, currently.
I've been building code on the net since it was the ARPAnet and the overall structure of pywikipedia simply flies in the face of conventions.
Were it not for the CONTENTS file, anyone downloading the code for the first time would be utterly lost.
The "docs" directory is a similar joke. If the instructions contained within it are so straight forward, why doesn't the "Installation script" do it automatically? ... oh, that's right, there IS NO installation script!!!
I first started trying to use pywikipedia on a private MediaWiki ... where "private" according to your definitions means NOT part of wikipedia.com. I downloaded it from the SVN at the end of June, just before you began converting to GIT.
Being used to things like Perl and MacPorts, getting pywikipedia working has been a painful experience.
As a Python and PHP person, I tend to say the same about anything that isn't Python or PHP!
I am a retired Unix SysAdmin, however, when I retired in 2003, Python was not yet a widely used language (and git had not yet been invented).
Your installation instructions still do not acknowledge the fact that "generate_family_file.py" is BROKEN.... that you CANNOT have a "user-config.py" file if you want to run it. "... Before you attempt to create one using the instructions below execute python generate_family_file.py. If it succeeds, ..." It CAN NOT succeed if you have followed the instructions up to that point, especially the step immediately before it where you are instructed to build "user-config.py" http://www.mediawiki.org/wiki/Manual:Pywikipediabot/Use_on_third-party_wikis
I've never had this problem, ever. I add new wikis to my Pywikipedia configuration all the time using generate_family_file.py without a problem.
The page: http://www.mediawiki.org/wiki/Manual:Pywikipediabot/Installation is simply an instruction on using GIT. I've already updated the page: http://www.mediawiki.org/wiki/Manual:Pywikipediabot/Mac to reflect "Mountain Lion," and to reflect this problem with the instructions.
I realize that I'm in a severe minority here, being both a Unix and OSX (i.e. Mac) person in a Windows based world, but I can live with the Windows distortions as I have been doing for the past 30 years. That is one reason why I have not had anything to say perviously... that plus the fact that I just barely have pywikipedia working for the MediaWiki I'm working on -- LOTRO-wiki.com.
A lot of F(L)OSS developers including Pywikipedia developers use *NIX as primary operating systems. There are bot runners that have success on both Windows and *NIX based systems.
But if you are going to package this software to look like a "correct" (i.e. conventional) Internet download, you need to fix things like the README file!
I realize also that from a developers point of view, maintaining a WIKI is a PAIN !!!! it is much easier to stay inside one's text editor (or whatever tool is being used to write and modify the code with) and to update things like the "CONTENTS" and "README" files. But that is a choice you have made... transferring your documentation from "standard" internet style to Wiki style. However, that choice implies much more work is necessary to keep the two in sync.
Maintaining any documentation is a pain, I actually find it easier to maintain a wiki however (I take no credit for the Pywikipedia documentation, it is something I tried to start some interest in cleaning up before, but nothing became of that), and it's rather fitting since this is a tool to be used with wikis.
One last point -- since you have these assorted "configure" scripts which MUST be run before one can begin using the product -- why not have an "install" script, which automatically runs them as needed. ... of course to do that, you will first need to fix "generate_family_file.py".
I wouldn't say that's really necessary, all you have to do is run generate_family_file.py and generate_user_files.py ... they are both pretty simple and quick. It's actually considerably easier than when I started using Pywikipedia, when you had to craft the family file by hand!
(I'll update the OSX instructions once I figure out how to use GIT. Fortunately, Apple includes the GIT client as part of OSX. )
T.T.F.N. William H. Magill # iMac11,3 Core i7 [2.93GHz - 8 GB 1067MHz] OS X 10.8.4 # MacBook Pro4.1 Core 2 Duo [2.5GHz - 4GB 667] OS X 10.6.8 # Macmini6,1 Intel Core i5 [2.5 Ghz - 4GB 1600MHz] OS X 10.8.3
magill@icloud.com magill@mac.com whmagill@gmail.com
Pywikipedia-l mailing list Pywikipedia-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/pywikipedia-l