User:Mindrones/Wiki/Proposals/2009/Ref

From BlenderWiki

Jump to: navigation, search
Note: This is an archived version of the Blender Developer Wiki. The current and active wiki is available on wiki.blender.org.

Structure

Actual situation

Calling a "branch" the first pseudo-folder in urls, these are the bigger branches in wiki's "Main" namespace. This is quite flat, since there aren't sub-levels other  than these (except for Scripts that is quite structured): 

Tutorials (many languages)
Manual (many languages)
BSoD  (many languages)
Reference (many languages)
Release notes (some languages)
Scripts
BlenderDev
Requests (many languages - should be under BlenderDev)
Hackers Guide (should be under BlenderDev)
GameEngine
GameEngineDev
Yafraydev (small)
Bf-documentation
Bf-institute
Books
Competitive analysis
Sandbox
Meta

There are many others, but they "contain" a few pages.

Ton's proposal

This is what Ton proposed in bf-docboard mailing list: 

See also 2.3:
http://download.blender.org/documentation/htmlI/
http://download.blender.org/documentation/htmlII/

Her's my raw picture how to classify documents;

- Learning Blender
   - general workflow tutorials (creating projects)
   - feature related tutorials (i.e. texturing)

- Manual (descriptive overviews by feature)
   - UI conventions
   - Blender files
   - Modeling
   - Materials/shaders
   - Game engine
   - Python overview
   - etc

- Reference (editors, buttons, menus, hotkeys etc)
   - Installation
   - User presets
   - Screens/areas
   - 3D window
   - Ipo window
   - etc

- Extending Blender
  - Python
  - Plugins

- Contributions
   - stuff to be reviewed
   - feature proposals
   - case studies
   - and everything that's not classifyable, or opiniated, or too personal :)

Here we have the chapters structure in the old manual.

PART I 

I. Introduction to Blender

    1. Introduction
    2. Installation
    3. Understanding the interface
        Blender's Interface Concept
        Navigating in 3D Space
        The vital functions
    4. Your first animation in 30 + 30 minutes

II. Modelling, Materials and Lights

    5. ObjectMode
    6. Basic Mesh Modelling
    7. Advanced Mesh Modelling
    8. Meta Objects
    9. Curves and Surfaces
    10. Materials and Textures
    11. Textures
    12. Lighting
    13. The World and The Universe
    
III. Animation

    14. Animation of Undeformed Objects
    15. Animation of Deformations
    16. Character Animation

IV. Rendering

    17. Rendering
    18. Radiosity
    19. Raytracing

V. Advanced Tools

    20. Particles
    21. Other Effects
    22. Special modelling techniques
    23. Soft bodies
    24. Volumetric Effects
    25. Sequence Editor
    
VI. Extending Blender

    26. Python Scripting
    27. Blender's Plugins System

VII. Beyond Blender

    28. Yafray as an Integrated External Renderer
    29. From Blender to YafRay Using YableX
    30. YafRay

Glossary

PART II 

I. Reference

    Blender windows - general introduction
    HotKeys In-depth Reference
    Windows Reference
    Buttons Reference
    Command Line Arguments
    	    
II. Appendices

    Hotkeys Reference
    Supported videocards
    The Licenses
    The Blender Documentation Project
    Troubleshooting (-)


Mediawiki API and mwclient

Mediawiki has a php API that can be used to obtain dat about the wiki.
Go at http://wiki.blender.org/api.php to see some example of it or have a look at the queries you can do.

Reading the clients list I've discovered an excellent python client called mwclient.

Here is an example of how to build a list with all the pages in the "Main" namespace and in the "User:" mainspace: 

#! /usr/bin/env python
 
import mwclient
site = mwclient.Site('wiki.blender.org',path='')
at_root=0
mylist=[]
for page in site.allpages(namespace=0):
  mylist.append(page.name)
  if '/' not in page.name: at_root+=1
titles=sorted(mylist)
mylist=[]
for page in site.allpages(namespace=2):
  mylist.append(page.name)
titles+=sorted(mylist)
print '\nThere are %s pages, %s at the main root\n' % (len(titles),at_root)

Today (2008/12/14) you'll find about 4400 pages. 300 of them are at the main root (that is, not within a structure).

If you want to try it, place this script in a folder as 'bwiki.py', then download the mwclient folder in the same folder of bwiki.py. In the shell, go to the folder that contains bwiki.py and mwclients folder and run python. Then type 

>exec file('bwiki.py')

or use the complete path to bwiki.py if you have problems.

Making a graph of the wiki's structure

So, I've tried to graph this scary monster :) This script below is rather naive and have to be fixed I'm sure, but it let you navigate the structure of the wiki tree, which Campbell has put here blender_wiki_081213.png (BEWARE this is a huge 30MB image, be kind with Blender's servers :)

Please download it only if you are interested, or if you really can't run the script below. 

#! /usr/bin/env python
 
def main():
  import mwclient
  site = mwclient.Site('wiki.blender.org',path='')
 
  import pydot
  bwiki_dot=open('bwiki.dot','w')
  graph_header='''digraph graphname{
 
  graph [
    fontname = "Helvetica-Oblique",
    fontsize = 36,
    label = "BlenderWiki",
  ];
 
  node [
    color = white,
    style = filled,
    fontname = "Helvetica-Outline"
  ];
 
'''
  bwiki_dot.write(graph_header)
 
  colors={0:'orangered',1:'yellow',2:'greenyellow',3:'goldenrod2',\
          4:'dodgerblue1',5:'thistle2',6:'lemonchiffon2'}
  print "reading data + building the tree (quick)..."
  nodes=[]
  links=[]
  for page in site.allpages(namespace=0):
    if '/' in page.name and not page.redirect:
      urlist=page.name.encode('utf-8').split('/')
      for index,name in enumerate(urlist):
 
        name='/'.join(urlist[:index+1])
        label=urlist[index]
        label_line='"%s" [label="%s", color="%s"];\n' % (name,label,colors[index])
        if name not in nodes:
          bwiki_dot.write(label_line)
          nodes.append(name)
 
        if index<len(urlist)-1:
          c_name='/'.join(urlist[:index+2])
          c_label=urlist[index+1]
          label_line='"%s" [label="%s", color="%s"];\n' % (c_name,c_label,colors[index+1])
          if c_name not in nodes:
            bwiki_dot.write(label_line)
            nodes.append(c_name)
          if (name,c_name) not in links:
            link_line='"%s" -> "%s"\n' % (name,c_name)
            bwiki_dot.write(link_line)
            links.append((name,c_name))
 
 
  bwiki_dot.write('}\n')
  bwiki_dot.close()
 
  print "creating graph (takes a lot of time)..."
  g=pydot.graph_from_dot_file('bwiki.dot')
  print "creating image (takes some time)..."
  g.write_png('bwiki.png', prog='fdp')
 
if __name__ == '__main__':
    main()

As I wrote above, place this script in a folder as 'bwiki-tree.py', together with the mwclient folder. In the shell, go to the folder that contains bwiki-tree.py and mwclients folder and run python. Then type 

exec file('bwiki-tree.py')

or use the complete path to bwiki-tree.py if you have problems.


Useful wiki extensions

ImageMap

http://www.mediawiki.org/wiki/Extension:ImageMap

Captcha

TagAsCategory

Todo_Tasks

http://www.mediawiki.org/wiki/Extension:Todo_Tasks

DynamicPageList

http://www.mediawiki.org/wiki/Extension:DynamicPageList

CodeTag

http://www.mediawiki.org/wiki/Extension:GeSHiCodeTag

Workflow

Comment systems

Rating and reviewing systems

have to test this but this sounds useful since ii's commenting +rating+captcha
this is fine if you try this on suggested websites that use it

Searching engines

Site map

http://www.mediawiki.org/wiki/Extension:ManualSitemap useful to help searching from outside the wiki

Blogging via mail

Retrieving categories and tags via python/xmlrpc

Since WordPress uses an XML-RPC interface, we can setup a simple script to retrieve categories and tags from a blog. This is a very simple example I made for a blog I admin: 

#! /usr/bin/env python

import xmlrpclib
from pprint import pprint

server = xmlrpclib.ServerProxy("http://dirittianimali.wordpress.com/xmlrpc.php")
user = 'USERNAME'
pwd = 'PASSWORD'

print '\nCATEGORIES:\n'+'='*50
pprint(server.wp.getCategories('',user,pwd))

print '\nTAGS:\n'+'='*50
pprint(server.wp.getTags('',user,pwd))

It outputs data as lists of dictionaries (here I print them of course) so we might use them for adding categories to wiki pages with mwclient for example: 

CATEGORIES:

[{'categoryDescription': '',
  'categoryId': '13514905',
  'categoryName': 'adottati',
  'description': 'adottati',
  'htmlUrl': 'http://dirittianimali.wordpress.com/category/adozioni/adottati/',
  'parentId': '750835',
  'rssUrl': 'http://dirittianimali.wordpress.com/category/adozioni/adottati/feed/'},

 ...

 {'categoryDescription': '',
  'categoryId': '13620180',
  'categoryName': 'gatti da adottare',
  'description': 'gatti da adottare',
  'htmlUrl': 'http://dirittianimali.wordpress.com/category/adozioni/gatti-da-adottare/',
  'parentId': '750835',
  'rssUrl': 'http://dirittianimali.wordpress.com/category/adozioni/gatti-da-adottare/feed/'}]

TAGS:

[{'count': '1',
  'html_url': 'http://dirittianimali.wordpress.com/tag/ba-bari/',
  'name': '(BA) Bari',
  'rss_url': 'http://dirittianimali.wordpress.com/tag/ba-bari/feed/',
  'slug': 'ba-bari',
  'tag_id': '14327151'},

 ...

 {'count': '22',
  'html_url': 'http://dirittianimali.wordpress.com/tag/cane/',
  'name': 'cane',
  'rss_url': 'http://dirittianimali.wordpress.com/tag/cane/feed/',
  'slug': 'cane',
  'tag_id': '19453'},

 ...

 {'count': '9',
  'html_url': 'http://dirittianimali.wordpress.com/tag/gatto/',
  'name': 'gatto',
  'rss_url': 'http://dirittianimali.wordpress.com/tag/gatto/feed/',
  'slug': 'gatto',
  'tag_id': '512148'},

 ...]

Apart form the obvious benefit of having the application for managing tags already in place, we might also benefit from having RSS feeds of categories and tags. Documenters would only have to read the feed with their RSS feed aggregator of choice (Mozilla Thunderbird for example) to receive commits well categorized.

Example of a "cani-da-adottare" Category page and of a "cani-da-adottare" Category feed.
Example of a "cane" Tag page and of a "cane" Tag feed.

Parsing wikitext

From here, here and here we can extract a list of python scripts that let you convert from wikitext to structures/html/xml/... After a brief look I've chosen these:

With some time at hand we should review them and see what can be useful for our purposes.

See also

External links

discussion in mailing list

mediawiki

wiki structure graph

wordpress xmlrpc interface

Retrieved from "https://wiki.blender.org/index.php/User:Mindrones/Wiki/Proposals/2009/Ref"