Site Documentation

Why Do I Need It?

Unfortunately Drupal does not include the powers of immortality or invincibility. You may someday get hit by a truck, or even just decide that you no longer want to maintain the site. So someone else may have to take over.

Where do they start? I know you documented the site really well, but the next person doesn't want to read those 14 binders of documentation you left behind. They can always go through all the administration screens and look for the information, but that can take a lot of time and even those pages don't tell you everything. Some things you're only going to get by looking directly into the database.

This is what the Site Documentation module is designed to do. In addition, it will detect some problems that may exist in your installation, and optionally correct some of them.

What Does It Do?

To simplify it a bit, the Site Documentation module picks up information from various places within the Drupal environment. Some of the information comes from internal arrays, some is derived from system calls, and some comes directly from the database tables. As one might imagine, this gathering does not come without a price; you can expect a spike in database and CPU activity while this module runs. Therefore, one should be careful how often and when it is run.

The Site Documentation module presents the following summarized information:

• Basic Drupal summary - lists some basic information about your Drupal installation.
• Database summary - list all tables and pertinent information.
• Sequences Summary - displays the last id of various table entries.
• Node Summary - lists how many of all content types are in the database, along with status information.
• Node Access Summary - checks the node_access table to see if all nodes are represented, and includes the ability to see which nodes are in which realms. (Unlike Devel Nodes Access, this does not require any other modules like Views.)
• Content types - detailed list of content type settings.
• Vocabularies - shows all the defined vocabularies (taxonomies) and all the terms within them, along with usage counts and other settings.
• Modules - lists all modules that are known to the Drupal system, even if not enabled. This list is much like that of the Modules Admin page (I borrowed some of that code), and includes dependencies. This now also includes path checking to help detect module in the wrong places.
• Themes - lists all the available themes, whether enabled or not.
• Theme_Engine - shows which theme engines are available.
• System Variables - lists all variables defined by all modules, along with their content.
• Blocks - shows a complete list of the blocks that are defined, whether enabled or not. It will also check to see if the theme that owns them exists any longer; if not, a warning message may be issued.
• Boxes - this shows additional information for manually created blocks.
• Roles and Permissions - lists all user roles along with their access permissions, blocks that are restricted to the role, and may include all users assigned to the role.
• Contacts - displays all email contacts for the site.
• Profile Fields - shows custom user profile fields used on this site.
• URL Aliases - shows URL Aliases that are defined along with broken and duplicate links. The alias numbers and node IDs are hyper linked to ease corrections.

I had discovered some time ago, that the "blocks" table can have rows defined for themes that were tested and discarded. This module allows you to delete them if you would like. If any are found, a warning message will be issued, and if you haven't chosen to automatically delete them, there will be a SQL statement at the end that you can copy and paste into phpMyAdmin.

In my testing, I discovered that I had rows in my "term-nodes" table that belonged to nodes that no longer existed. So I added a check and a delete option that you may choose to run. If you check and don't delete, there will be a SQL statement at the end that you can copy and paste into phpMyAdmin.

Another problem that cropped up in my creating this module was a long-running / never-ending Cron job. This module will now highlight that and gives you an option to fix it.

Dynamic web sites can create a lot of "empty" space in some tables, especially the cache tables; this is called "overhead" by MySql. There is an option that allows you to issue an "optimize" statement against the tables to release that overhead.

Change Note

Starting with releases available November 4, 2008, the report sections are now scrollable to limit the report width. The CSS contains a comment on how to disable this if desired.

Translation

I have started running the translation extractor when I update the module, so if someone wants to provide translations, the template is available. Please open a feature request with the translation (.po) module.

Hook_sitedoc

I'm still looking for module developers to give me some idea of what they would want to show up on this report and how they would like to return it to me.

How Did It Do For You?

Feel free to write and let me know what kind of surprises you found with this module. I can all but guarantee you will find some.

Development version status

The development versions (-dev, which rolls up at Noon and Midnight GMT) are where the newest stuff is, including any bug fixes and new features. We try to make sure it is tested before we commit anything, but occasionally a bug will get by us. Your help on testing this code is greatly appreciated. The translation templates may not always be up-to-date in the dev releases.

Current Features being tested in Development

• none

For more about NancyDru, see this page.