From 66a11cc586584516a3c66bca5c084840565fdad5 Mon Sep 17 00:00:00 2001 From: Offray Luna Date: Thu, 6 Apr 2017 11:49:28 +0000 Subject: [PATCH] Several improvements on GrafoscopioDocumentation and GrafoscopioDockingBar for updating documentation and made it more modular and related to a specific package in a particular repository. Part of the dialogue while writing the JOSS papers. --- .../GrafoscopioDockingBar.class.st | 24 ++---- .../GrafoscopioDocumentation.class.st | 73 +++++++++++++++- .../Grafoscopio/GrafoscopioNode.class.st | 25 +++++- .../Grafoscopio/GrafoscopioNotebook.class.st | 84 ++++++++----------- .../Grafoscopio/ManifestGrafoscopio.class.st | 7 +- 5 files changed, 136 insertions(+), 77 deletions(-) diff --git a/repository/Grafoscopio/GrafoscopioDockingBar.class.st b/repository/Grafoscopio/GrafoscopioDockingBar.class.st index a6e202e..9e26206 100644 --- a/repository/Grafoscopio/GrafoscopioDockingBar.class.st +++ b/repository/Grafoscopio/GrafoscopioDockingBar.class.st @@ -441,7 +441,7 @@ GrafoscopioDockingBar class >> start [ updateMenu := MenuMorph new. updateMenu add: 'Grafoscopio' target: self selector: #updateGrafoscopioUI; - add: 'Documentation' target: self selector: #updateDocumentationUI; + add: 'Documentation' target: GrafoscopioDocumentation selector: #updateAll; add: 'DataViz package' target: self selector: #updateDatavizUI; add: 'Notebooks places' target: GrafoscopioDocumentation selector: #updateDocsPlaceUI; "add: 'Database engine' target: ExternalApp selector: #installSQLite32BitsUI; @@ -451,10 +451,11 @@ GrafoscopioDockingBar class >> start [ helpMenu := MenuMorph new. helpMenu - add: 'Tutorial (Spanish)' target: (GrafoscopioNotebook new) selector: #openTutorial; - add: 'Manual' target: (GrafoscopioNotebook new) selector: #openManual; + add: 'Tutorial (Spanish)' target: GrafoscopioDocumentation selector: #openTutorial; + add: 'Manual' target: GrafoscopioDocumentation selector: #openManual; add: 'Manual (PDF)' target: GrafoscopioDocumentation selector: #openPDFManual; - add: 'Dev''s notes' target: (GrafoscopioNotebook new) selector: #openDevNotes; + add: 'Dataviz' target: GrafoscopioDocumentation selector: #openDatavizIntro; + add: 'Dev''s notes' target: GrafoscopioDocumentation selector: #openDevNotes; add: 'About Grafoscopio' target: self selector: #messageAbout. dockingBar := DockingBarMorph new. @@ -492,18 +493,6 @@ GrafoscopioDockingBar class >> updateDatavizUI [ ifFalse: [self inform: 'Actualización del paquete dataviz no realizada']] ] -{ #category : #updating } -GrafoscopioDockingBar class >> updateDocumentationUI [ - "Updates documentation (manual, tutorials) from official repository" - - | update | - - update := (UIManager default - confirm: 'Do you wish to update the documentation?' - label: 'Update documentation'). - update ifTrue: [GrafoscopioDocumentation update] -] - { #category : #updating } GrafoscopioDockingBar class >> updateGrafoscopio [ "Updates Grafoscopio with new versions of itself take from the source code repository and @@ -636,7 +625,8 @@ GrafoscopioDockingBar class >> updateUI [ "I update the User Interface (UI) with new versions of the docking bar or logos where available. I'm helpful while testing new functionality that should be expossed to the user via the UI" self start. - (World submorphs select: [ :each | each class = DockingBarMorph ]) allButFirstDo: [ :bar | bar delete ]. + (World submorphs select: [ :each | each class = DockingBarMorph ]) + allButFirstDo: [ :bar | bar delete ]. ] diff --git a/repository/Grafoscopio/GrafoscopioDocumentation.class.st b/repository/Grafoscopio/GrafoscopioDocumentation.class.st index 1b4dd47..91cb8ca 100644 --- a/repository/Grafoscopio/GrafoscopioDocumentation.class.st +++ b/repository/Grafoscopio/GrafoscopioDocumentation.class.st @@ -88,14 +88,45 @@ GrafoscopioDocumentation class >> listOutdated [ ] { #category : #updating } -GrafoscopioDocumentation class >> listOutdatedDocsIn: aDocumentsCollection [ +GrafoscopioDocumentation class >> listOutdatedDocsIn: aDocumentsName [ "I return the list of all documentent where the local copy and the remote copy doesn't match" - ^ aDocumentsCollection select: [ :doc | (self isFileUpdatedFor: doc) = false ] + ^ (self perform: aDocumentsName asSymbol) documents reject: [ :doc | (self isFileUpdatedFor: doc) ] ] -{ #category : #'as yet unclassified' } +{ #category : #updating } +GrafoscopioDocumentation class >> listOutdatedIn: aGrafoscopioDocumentation [ + "I return the list of all documentent where the local copy and the remote copy doesn't match" + self listOutdatedDocsIn: (self perform: aGrafoscopioDocumentation) documents +] + +{ #category : #operation } GrafoscopioDocumentation class >> openDatavizIntro [ - self shouldBeImplemented. + self openNotebookFrom: 'dataviz' At: 1 +] + +{ #category : #operation } +GrafoscopioDocumentation class >> openDevNotes [ + self openNotebookFrom: 'current' At: 3 +] + +{ #category : #operation } +GrafoscopioDocumentation class >> openManual [ + "I open the proper notebook in the adecuate documentation." + self openNotebookFrom: 'current' At: 2 +] + +{ #category : #operation } +GrafoscopioDocumentation class >> openNotebookFrom: aDocumentation At: index [ + "I open a notebook included with the documentation, located at a given index" + | notebookTemp gfcDocs | + gfcDocs := self perform: aDocumentation asSymbol. + (index between: 1 and: gfcDocs documents size) + ifFalse: [ ^ self ] + ifTrue: [ + notebookTemp := (gfcDocs localPlace fullName, '/', (gfcDocs documents at: index)) asFileReference. + notebookTemp exists + ifTrue: [GrafoscopioNotebook new openFromFile: notebookTemp] + ifFalse: [ self updateUIFor: aDocumentation ]] ] { #category : #operation } @@ -108,6 +139,12 @@ GrafoscopioDocumentation class >> openPDFManual [ UnixProcess command: 'xdg-open ', (docs localPlace / pdfManual) fullName. ] +{ #category : #operation } +GrafoscopioDocumentation class >> openTutorial [ + "I open the proper notebook in the adecuate documentation." + self openNotebookFrom: 'current' At: 1 +] + { #category : #updating } GrafoscopioDocumentation class >> update [ self isUpdated @@ -118,11 +155,39 @@ GrafoscopioDocumentation class >> update [ ] +{ #category : #updating } +GrafoscopioDocumentation class >> update: aDocumentationName [ + (self listOutdatedDocsIn: aDocumentationName) + ifEmpty: [ + self inform: 'All documents in the ', aDocumentationName,' collection are already updated'. + ^ self ] + ifNotEmpty: [:outdatedDocs | + outdatedDocs do: [ :eachDoc | self download: eachDoc]. + self inform: 'Updating of ', aDocumentationName,' documentation finished.' ] +] + +{ #category : #operation } +GrafoscopioDocumentation class >> updateAll [ + self + update: 'current'; + update: 'dataviz' +] + { #category : #updating } GrafoscopioDocumentation class >> updateDocsPlaceUI [ self current localPlace: (UIManager default chooseDirectory: 'Path to the documentation folder') ] +{ #category : #updating } +GrafoscopioDocumentation class >> updateUIFor: aDocumentationName [ + "Updates documentation (manual, tutorials) from the official repository for a given documentation." + | update | + update := (UIManager default + confirm: 'Do you wish to update the ', aDocumentationName,' documentation?' + label: 'Update ', aDocumentationName, ' documentation'). + update ifTrue: [ self update: aDocumentationName ] +] + { #category : #accessing } GrafoscopioDocumentation >> documents [ ^ documents ifNil: [ documents := OrderedCollection new ] diff --git a/repository/Grafoscopio/GrafoscopioNode.class.st b/repository/Grafoscopio/GrafoscopioNode.class.st index 0045536..5741878 100644 --- a/repository/Grafoscopio/GrafoscopioNode.class.st +++ b/repository/Grafoscopio/GrafoscopioNode.class.st @@ -210,6 +210,7 @@ GrafoscopioNode >> becomeDefaultTestTree [ node1 := self class new header: 'Markup'; body: 'I am just a node with markup'; + links: 'temp.md'; level: 1. node2 := self class new header: 'Code'; @@ -406,12 +407,12 @@ GrafoscopioNode >> exportPreambleTo: aStream [ { #category : #exporting } GrafoscopioNode >> flatten [ "I traverse the tree looking for node bodies containing 'Text' objects and transform them to - their string content, so space is saved and storage format is DVCS friendly while serializing them to STON" + their string content, so space is saved and storage format is DVCS friendly while serializing + them to STON" (self preorderTraversal) do: [ :eachNode | (eachNode body class = Text) - ifTrue: [eachNode body: (eachNode body asString)] - ] + ifTrue: [eachNode body: (eachNode body asString)]] ] { #category : #exporting } @@ -557,7 +558,18 @@ GrafoscopioNode >> links [ { #category : #accessing } GrafoscopioNode >> links: anObject [ - links add: anObject + self links add: anObject +] + +{ #category : #operation } +GrafoscopioNode >> linksToMarkdownFile [ + "I detect if the links contains any reference to a file ending in '.md' or '.markdown'" + self links ifNotNil: [ + self links + detect: [:l | (l endsWith: '.md') or: [ l endsWith: '.markdown']] + ifFound: [ ^ true ] + ifNone: [^ false]] + ] { #category : #exporting } @@ -750,6 +762,11 @@ GrafoscopioNode >> saveContent: anObject [ body := anObject ] +{ #category : #operation } +GrafoscopioNode >> selectMarkdownSubtreesToExport [ + ^ (self root preorderTraversal) select: [ :each | each linksToMarkdownFile ]. +] + { #category : #accessing } GrafoscopioNode >> specModelClass [ diff --git a/repository/Grafoscopio/GrafoscopioNotebook.class.st b/repository/Grafoscopio/GrafoscopioNotebook.class.st index 29bce1a..0718ceb 100644 --- a/repository/Grafoscopio/GrafoscopioNotebook.class.st +++ b/repository/Grafoscopio/GrafoscopioNotebook.class.st @@ -96,10 +96,12 @@ GrafoscopioNotebook >> demoteNode [ ] { #category : #persistence } -GrafoscopioNotebook >> exportAllSubtreesAsMarkdow [ - +GrafoscopioNotebook >> exportAllSubtreesAsMarkdow [ | toBeExported | - toBeExported := (self notebook preorderTraversal) "collect: [ :each | each links last ] " + toBeExported := self notebook selectMarkdownSubtreesToExport. + toBeExported ifEmpty: [ ^ self ]. + toBeExported do: [ :each | self subtreeAsMarkdownFor: each ]. + self inform: toBeExported size asString , ' exported markdown subtrees.' ] { #category : #persistence } @@ -168,8 +170,7 @@ GrafoscopioNotebook >> exportNode: aGrafoscopioNode asMarkdownIn: aFile [ aFile exists ifTrue: [ aFile delete ]. aFile ensureCreateFile; - writeStreamDo: [:stream | stream nextPutAll: aGrafoscopioNode asMarkdown]. - self inform: ('Exported as: ', String cr, aFile fullName) + writeStreamDo: [:stream | stream nextPutAll: aGrafoscopioNode asMarkdown] ] { #category : #api } @@ -261,12 +262,15 @@ GrafoscopioNotebook >> moveNodeBefore [ { #category : #utilities } GrafoscopioNotebook >> navigateRelativePathFor: aFileString [ - "Given a relative path according to location of the notebook's workingFile, I navigate to that file if exist and create it, including - subdirectories if it does not exist. - If the relative path is located in a subdirectory that shares the route with the notebooks working file, it must start with the folders name, + "Given a relative path according to location of the notebook's workingFile, + I navigate to that file if exist and create it, including subdirectories if it does not exist. + If the relative path is located in a subdirectory that shares the route with the notebooks working + file, it must start with the folders name, without using './' to point the same shared root " | finalLocation pathSegments | + aFileString ifEmpty: [ ^ self ]. + aFileString asUrl host ifNotNil: [ ^self ]. finalLocation := workingFile parent. pathSegments := aFileString splitOn: '/'. pathSegments allButLastDo: [ :segment | @@ -370,25 +374,6 @@ GrafoscopioNotebook >> openDefault [ ^ nb openWithSpec. ] -{ #category : #persistence } -GrafoscopioNotebook >> openDevNotes [ - self openDocumentationNotebookAt: 3. -] - -{ #category : #persistence } -GrafoscopioNotebook >> openDocumentationNotebookAt: index [ - "I open a notebook included with the documentation, located at a given index" - | notebookTemp gfcDocs | - gfcDocs := GrafoscopioDocumentation current. - (index between: 1 and: gfcDocs documents size) - ifFalse: [ ^ self ] - ifTrue: [ - notebookTemp := (gfcDocs localPlace fullName, '/', (gfcDocs documents at: index)) asFileReference. - notebookTemp exists - ifTrue: [self class new openFromFile: notebookTemp] - ifFalse: [ GrafoscopioDockingBar updateDocumentationUI ]] -] - { #category : #persistence } GrafoscopioNotebook >> openFromFile: aFileName [ "I open a notebook from a file named aFileName containing a grafoscopio tree" @@ -436,22 +421,12 @@ GrafoscopioNotebook >> openFromUrlUI [ | fileUrl | "GrafoscopioBrowser configureSettings." fileUrl := UIManager default - textEntry: 'Ingrese la URL' - title: 'Nuevo documento desde URL'. + textEntry: 'Enter the URL' + title: 'Open notebook from URL'. fileUrl isNil ifTrue: [ ^nil ]. self class new openFromUrl: fileUrl ] -{ #category : #persistence } -GrafoscopioNotebook >> openManual [ - self openDocumentationNotebookAt: 2. -] - -{ #category : #persistence } -GrafoscopioNotebook >> openTutorial [ - self openDocumentationNotebookAt: 1. -] - { #category : #'editing nodes' } GrafoscopioNotebook >> pasteNodeFromClipboard [ tree highlightedItem content pasteFromClipboard. @@ -531,7 +506,6 @@ GrafoscopioNotebook >> saveToFile: aFileReference [ [ self exportAsSton: self notebook on: (self workingFile writeStream)] ensure: [ (self workingFile writeStream) ifNotNil: #close ]. self title: self workingFile basenameWithIndicator, ' | Grafoscopio notebook'. - self exportAllSubtreesAsMarkdow. self inform: ('File saved at: ', String cr, self workingFile fullName). GrafoscopioDockingBar updateRecentNotebooksWith: aFileReference. @@ -563,12 +537,20 @@ GrafoscopioNotebook >> saveWorkingNotebook [ ] { #category : #persistence } -GrafoscopioNotebook >> subTreeAsMarkdown [ - | currentNode exportedFile | +GrafoscopioNotebook >> subtreeAsMarkdown [ + | currentNode | currentNode := tree highlightedItem content. - currentNode links last ifNil: [ ^self ]. - exportedFile:= self navigateRelativePathFor: currentNode links last. - self exportNode: currentNode asMarkdownIn: exportedFile + self inform: ('Exported as: ', String cr, (self subtreeAsMarkdownFor: currentNode) fullName ) +] + +{ #category : #persistence } +GrafoscopioNotebook >> subtreeAsMarkdownFor: aNode [ + | exportedFile | + aNode links ifEmpty: [ ^ self ]. + exportedFile:= self navigateRelativePathFor: aNode links last. + exportedFile class = GrafoscopioNotebook ifTrue: [ ^ self ]. + self exportNode: aNode asMarkdownIn: exportedFile. + ^ exportedFile ] { #category : #'editing nodes' } @@ -602,6 +584,12 @@ GrafoscopioNotebook >> topBar [ description: 'Save notebook'; icon: Smalltalk ui icons glamorousSave; action: [ self saveWorkingNotebook ] ]. + group addItem: [ :item | + item + name: nil; + description: 'Export all markdown subtrees'; + icon: Smalltalk ui icons glamorousMore; + action: [ self exportAllSubtreesAsMarkdow ] ]. group addItem: [ :item | item name: nil; @@ -676,12 +664,6 @@ GrafoscopioNotebook >> topBar [ description: 'Reload link'; icon: Smalltalk ui icons glamorousRefresh; action: [ self updateForSpecialLinks ] ]. - group addItem: [ :item | - item - name: nil; - description: 'Export subtree'; - icon: Smalltalk ui icons glamorousMore; - action: [ self subTreeAsMarkdown ] ]. group addItem: [ :item | item name: nil; diff --git a/repository/Grafoscopio/ManifestGrafoscopio.class.st b/repository/Grafoscopio/ManifestGrafoscopio.class.st index eb62805..f974317 100644 --- a/repository/Grafoscopio/ManifestGrafoscopio.class.st +++ b/repository/Grafoscopio/ManifestGrafoscopio.class.st @@ -12,6 +12,11 @@ ManifestGrafoscopio class >> ruleRBAssignmentInIfTrueRuleV1FalsePositive [ ^ #(#(#(#RGMethodDefinition #(#GrafoscopioNode #embedNodes #false)) #'2017-02-16T20:07:02.600781-05:00') #(#(#RGMethodDefinition #(#GrafoscopioNotebook #navigateRelativePathFor: #false)) #'2017-03-28T22:30:53.541042-05:00') ) ] +{ #category : #'code-critics' } +ManifestGrafoscopio class >> ruleRBBadMessageRuleV1FalsePositive [ + ^ #(#(#(#RGMethodDefinition #(#'GrafoscopioDocumentation class' #openNotebookFrom:At: #true)) #'2017-04-05T18:01:21.892153-05:00') ) +] + { #category : #'code-critics' } ManifestGrafoscopio class >> ruleRBBooleanPrecedenceRuleV1FalsePositive [ ^ #(#(#(#RGMethodDefinition #(#'GrafoscopioNode class' #cleanTreeRootReferences #true)) #'2017-03-27T22:18:17.447627-05:00') ) @@ -24,7 +29,7 @@ ManifestGrafoscopio class >> ruleRBClassNameInSelectorRuleV1FalsePositive [ { #category : #'code-critics' } ManifestGrafoscopio class >> ruleRBEqualsTrueRuleV1FalsePositive [ - ^ #(#(#(#RGMethodDefinition #(#'GrafoscopioDocumentation class' #listOutdated #true)) #'2016-10-09T10:16:31.841951-05:00') ) + ^ #(#(#(#RGMethodDefinition #(#'GrafoscopioDocumentation class' #listOutdated #true)) #'2016-10-09T10:16:31.841951-05:00') #(#(#RGMethodDefinition #(#'GrafoscopioDocumentation class' #listOutdatedDocsIn: #true)) #'2017-04-05T17:50:59.032741-05:00') ) ] { #category : #'code-critics' }