Docset Document Authoring Tutorial

ObjectiveWhat is Dash

• Programmer-oriented document library (MAC)
  
• Code Snippets Management Tools

This is an artifact that is highly recommended for those who are in the process of every day in various API documents.

Why do you make your own documents

• The official source does not have the relevant documentation
  
• Documents experience Better offline

Recently in the study of PHANTOMJS, the relative lack of documentation, mainly crossing Web tutorials and APIs, and encountered a problem is that the home network access to foreign sites too slow, the experience is too poor. It may be that the new reason for the technology is that there are no related documents in the dash, and after giving feedback to the dash author, I get the following reply:

I ' ve recorded your vote towards a PHANTOMJS docset. Currently, this docset has one votes. Please note that I don ' t generate docsets unless more users ask for them.


You can, however, generate your own docsets by following of instructions at Http://kapeli.com/docsets.

Oh, it seems that only their own hands, clothed.

Production TutorialsPremise

1. Mac system; Need to install Python environment, third-party library BS4
   
2. The original document is on the website (official web site so-called 7. Any HTML documentation), such as this example http://phantomjs.org/

To generate a site image

CD ~ && wget-m http://phantomjs.org/

In this example, using Wget's--mirror (-m) option to create a mirror site, the site's various layers of directories, files (Pictures, styles, HTML, etc.) are saved locally, which is the most original file to be imported to dash.

Text Processing

After the previous step to the local image file is likely to use an absolute path (such as <a href= "http://phantomjs.org/release-names.html"), want to offline index, You must first convert to a relative path (note the different hierarchical relationships), it is recommended that you perform a simple analysis, and then use the script for batching.

This step is an important step, it will affect the quality of the document, if not handled very likely some links due to the wrong path and can not see.

For example, I have different levels of substitution for domain names in HTML based on different directory hierarchies:

 for inch - D  Do ' s/http:..phantomjs.org/. \/.. \//g '$dirfor in-D$dirdo' s/http:..phantomjs.org/. \/.. \/.. \//g '$sub Done

Copy Document

Dash requires document files to be placed in the *.docset directory, at the default directory level:

Mkdir-p phantomjs.docset/contents/Resources/documents/ mv ~/phantomjs.org/* Phantomjs.docset/contents/Resources/documents/

Create a Info.plist file

Inside can define some configuration information, such as whether to allow JS, etc.

Touch Phantomjs.docset/contents/info.plist

<?xml version= "1.0" encoding= "UTF-8"?> <! DOCTYPE plist Public "-//apple//dtd plist 1.0//en" "Http://www.apple.com/DTDs/PropertyList-1.0.dtd" > <plist version="1.0"> <dict> <key>Cfbundleidentifier</key> <string>Phantomjs</string> <key>Cfbundlename</key> <string>Phantomjs</string> <key>Docsetplatformfamily</key> <string>Phantomjs</string> <key>Isdashdocset</key> <true/> </dict> </plist>

Build Index

• First create a SQLite database file and generate a table.

 CREATETABLEINTEGERPRIMARYKEYtext text  TEXT); . exit

• Populating an index with a python script

This step is also a more important step, but also the most complex step. The index of the database file corresponds to the directory (or index) of the dash document, and high-quality indexes can express rich hierarchical relationships and classifications, such as functions, classes, familiarity, modules, classifications, entries, commands, and so on.

For simplicity, this is only populated with 4 ' categories ' on the homepage of the official website, implemented in Python, and how to populate the script according to the actual document situation:

#!/usr/local/bin/pythonImport OS, Re, sqlite3 fromBS4 import BeautifulSoup, navigablestring, tagdb = Sqlite3.connect (' Phantomjs.docset/contents/resources/docset.dsidx ') cur = db.cursor ()Try: Cur.execute (' DROP TABLE searchindex; ') Except:passcur.execute (' CREATE TABLE searchindex (id INTEGER PRIMARY KEY, Name text, type text, path text); ') Cur.execute (' CREATE UNIQUE INDEX anchor on Searchindex (name, type, path); ') Docpath =' phantomjs.docset/contents/resources/documents 'page =Open(Os.path.join (Docpath,' index.html ')).Read() Soup = beautifulsoup (page) any= Re.compile (' ^[a-z]{3,20}$|documentation.html|faq.html ') forTaginchSoup.find_all (' A ', {' href ': any}): Name = tag.text. Strip ()if Len(name) >0: Path = tag.attrs[' href '].strip ()ifPath.Split(' # ')[0] not inch(' index.html ',' index.htm ',' bookindex.html '): Cur.execute (' INSERT OR IGNORE into Searchindex (name, type, path) VALUES (?,?,?) ', (name,' Category ', path)) print' name:%s, path:%s '% (name, path) Db.commit () db.Close()

Add icon and other comment notes, etc.

After making a logo (from the official website logo cut a large image), export two sizes, 16x16, 32x32

Touch phantomjs.docset/iconpng touch phantomjs.docset/icon@2x.png

At this point, double-clicking the phantomjs.docset can be imported into the Dash, you can also refresh the contents of the document in the preferences, if you have to modify the logo need to delete the document and then add it in.

Share to Community (GitHub)

Contribute your own efforts through the Internet.

• Fork Project Https://github.com/Kapeli/Dash-User-Contributions
  
• Upload your own files as required, and you can pull the request.

Reference

This article only records their own in the process of making documents basic ideas, please make sure to carefully refer to the official website of the tutorial:

• Generating Dash Docsets
  
• Kapeli/dash-user-contributions

Docset Document Authoring Tutorial