Seeking Help in Post Migration Cleanup - My Forums

Re: Seeking Help in Post Migration Cleanup

smashingred — Aug 17, 2013, 10:14 AM

Susan,

Thanks for posting your notes. Here's the process I've followed to import whole documents rather than cherry picking the content I take these steps

View source of original doc on confluence

Remove all markup above and including the following comment

Find the last piece of content in the main content page. This is often the See Also section and it's list (which won't actually be there because it's JavaScript Generated)

I then remove all the extraneous class styles such as the classes on the tables and div wrappers.

I then replace the class="code-java" with class="brush: php"

Info/Note boxes should be replaced by single div and have a single class of .info, .warning, .danger, .note. and the icon images should be removed.

I have come across some font tags here and there, those should also be removed as well.

What should remain is very clean markup with only those 5 classes above.

In the code view of the edit view in the new docs, replace all the content that was there with the new text.

Preview the changes and clean up any minor issues and save if none.

Be sure to leave a change comment. (like a commit message).

Re: Seeking Help in Post Migration Cleanup

sottwell — Aug 16, 2013, 07:30 AM

What I have discovered is that a bug in your import script skips sections of content when importing code segments. Every code segment will skip the actual code segment for that spot, plus all of the intervening content, until the next code segment.

I've worked out a few tricks for making things easier.

1. When copy/pasting code segments from the original, it's easier to insert some text like "code", make sure to add a few line breaks, then format your placeholder text as "php code". That will put it in the grey box. Now copy/paste the code from the original to replace the placeholder text in the box.

2. To get the anchor targets for the H- headers, finish the page with just the headers, then open the HTML view and copy/paste the whole into your favorite editor. Do a search/replace for all H2 and H3 elements, adding the appropriate A tags. for example

Making the Doodles Base Class

Then search for each H2 and H3 element and edit the last segment of the name attribute; the last segment, for example here "MakingtheDoodlesBaseClass", is simply the link text. Then when finished, just copy/paste your modified content back into the HTML view.

A few things that could have been done differently.
1. Anchor targets don't have to be A tags with a name attribute, anchors can link to ID attributes in the target element. There is still some controversy over which is preferable.

2. Images are enclosed in span tags, and also have inline styled borders. There's no reason why either of these are necessary if CSS is used to style the images in these pages' content area; for example the panel-content class could be used to indicate which container's img elements should be styled.

3. Something odd about the line numbers in the SyntaxHighlighter's plugin formatting; all code is shifted down one line. Possibly due to some CSS adding padding to pre elements that doesn't get applied to the gutter area? The extra spacing appears to be in the td class="code" element generated by SyntaxHighlighter. (see attached screenshot)

Re: Seeking Help in Post Migration Cleanup

BobRay — Aug 15, 2013, 10:48 PM

Jay, Excellent points, and you're right about the unfair advantage of platforms with limited classes.

The http://api.modx.com/revolution/2.2/ stuff is not bad at all (except for the missing examples). I think it would be nice for the initial display to collapse the properties and methods sections (or at least have a jump link to the methods), since you usually want one or the other. I'd also prefer "Class Variables" to "Properties" (or have "Class Variables" in parentheses after Properties) -- but maybe that's just me. I know it's technically correct as is, but in MODX the term "properties" is usually used to refer to things that end up in the $scriptProperties array (the properties in a snippet tag, in the default properties, or a property set), so it might confuse some new users.

I think PhpDoc allows you to insert information from an external file with a single-line comment, though the PhpDocumenter documentation is ironically horrible, imo, so I can't tell how it works. That might be a way to get the examples back in.

I also think that this is not a bad class reference (though I'm somewhat biased and it's missing the methods). http://bobsguides.com/modx-object-quick-reference.html

See, for example: http://bobsguides.com/modx-object-quick-reference.html#modResource

It's generated on the fly from the MODX Schema file, and because of the alias listing, I find it much more useful than the API docs.

I wonder if there's a way to put the file locations of the class files as comments (or something else) in the Schema file. That would allow auto-generated docs that combine the schema and the PhpDoc comments in the files. If you add to that a link to an HTML file with explanations and examples, and a category tag either in the Schema or the PhpDoc blocks, you'd really have something.

Putting reference lines in the Schema file is a cool idea (if it would work), because it would be compact and wouldn't affect speed at all since the Schema isn't used by MODX in its normal operations.

Re: Seeking Help in Post Migration Cleanup

smashingred — Aug 15, 2013, 10:22 PM

Bob,

The complete generated api reference is available at http://api.modx.com. We discussed this at length and are looking into ways to make this what it should be and avoid having to hand manage all of the the api docs in the future. What was in rtfm.modx.com was not generated by phpDoc as far as I know but was hand migrated by editors.

What we have in http://api.modx.com is sub optimal as it has no examples (those were removed from the source) and we are unable to augment and enhance the current generated docs. Ideally a hybrid approach using the generated docs with included examples and edge cases, and, augmented with broader examples and possibly tied to issues.

I can certainly add the API docs to both the main navs of xpdo, and Revo in the current documentation as a way for people to access the information in the short term until we can make them better. The API docs from ExtJs are brilliant as are the examples you've given. I would argue that api references for public apis for SaaS platforms with limited classes are at an unfair advantage when it comes to being able to have an amazing API, that's not an excuse to have unawesome references.

Open to more thoughts on this, for sure.

Re: Seeking Help in Post Migration Cleanup

BobRay — Aug 15, 2013, 10:11 PM

I'm most concerned about the API and Class Reference right now. I think the problem (I'm guessing here) is that the original API docs there were created with PhpDoc, then added to extensively (and inconsistently), so that now there's no way to use PhpDoc for them and no easy way to use wget or cURL either.

Imo, this is a great API reference: http://www.php.net/manual/en/funcref.php, though this is also pretty good (though incomplete): http://apidocs.mailchimp.com/api/2.0/

I'm not sure how either one is generated and maintained.

I just hate to see us create a new cobbled-together set of docs and have to face this problem again and again. MODX deserves world-class docs and having them would massively increase adoptions, imo.

Re: Seeking Help in Post Migration Cleanup

smashingred — Aug 15, 2013, 11:57 AM

Bob, we're open to suggestions or assistance with this. Jason trialled and tested the import, however, until we went live, few issues of missing content were detected. We probably could have had more people in earlier than later. I feel that the best course is banding together editors to have them manually review the pages and aid in making them right. It's merely my opinion and if we were able to find a better way to re-import content via automated process, that would be good. I may have another option up my sleeve.

Re: Seeking Help in Post Migration Cleanup

sottwell — Aug 15, 2013, 04:53 AM

The three "Doodles" pages are cleaned up. I think.

Re: Seeking Help in Post Migration Cleanup

BobRay — Aug 15, 2013, 03:46 AM

Ah.

I haven't found any Class Reference pages that are correct yet. Every one I've looked at is missing the syntax specification, the parameters, and the return type.

Also, on the xPDO Class Reference pages, the syntax spec, args, and return type are missing *and* all the links to the API seem to be dead:

http://api.modxcms.com/xpdo/om/xPDOObject.html#get

Maybe re-doing the regex for those pages would be in order rather than trying to fix them all by hand?

Re: Seeking Help in Post Migration Cleanup

smashingred — Aug 15, 2013, 12:54 AM

Quote from: BobRay at Aug 14, 2013, 11:32 PM

Jay, surely there's a way to automate that with either a markdown -> HTML translator or cURL?

What we have is the result of cURL (well wget) and regex. The problem is that the regex choked on edge cases and customizations in the markup. It still requires human intervention to repair and clean. Many docs were just fine, but some docs had issues.

Re: Seeking Help in Post Migration Cleanup

BobRay — Aug 14, 2013, 11:32 PM

Jay, surely there's a way to automate that with either a markdown -> HTML translator or cURL?