Seeking Help in Post Migration Cleanup

Hey folks. We recently moved the documentation from Confluence to MODX and due to Confluence's architecture, getting the data out cleanly was not possible. We are looking for help in ensuring the most visited sections of the documentation back in the state it was in.

Cleanups include reviewing docs to ensure what is in the original docs is in the new docs. This ideally would include the stripping or removal of some of the confluence classes and special formatting. The best approach is to grab the document source, clean it up and then paste it into the code view of Redactor in the edit view of the document at rtfm.modx.com

This will be just the first phase. The second phase will be a major initiative to improve the core documentation for Revolution, XPDO and etc.

If you would like to volunteer to help get the docs back into their pre-move state, please send an email to [email protected] including your username and I'll get you added. We will not have regular editors up and running for a couple weeks. We will have to issue you temporary credentials for front end editing.

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

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.

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?

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

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.

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.

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.

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.

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

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) [ed. note: sottwell last edited this post 11 years, 5 months ago.]