Build your own
Drupal API site


@rlnorthcutt

(drupal, twitter, gmail, fb, irc, etc.)


  • Developer with Jackson River, LLC
  • www.RealTidings.com
  • Drupal since 4.6
  • Husband and father
  • All around good guy...

    Ron Northcutt (me)

    Why Build your own Doc site?

    • for when you are without a connection (airplane, internet is down, staying at grandma's, etc.)

    • for convenience on your local

    • for your own custom code

    • for shared team resources

    • for funsies

    How to - the ""long"" way

    Manual install of the API module 

    1. Create Drupal site
    2. Install modules and libraries
    3. Set-up code repositories
    4. Set-up API module to index the code
      (for each project and branch)
    5. Run cron to index the sites

    How to - the short(er) way


    DrupalAPI Install Profile : 

    1. Install with profile
    2. Update code
    3. Customize

    Updating the docs for core

    Easy to update
    cd profiles/drupalapi
    ./update.sh 
    Then run cron many, many times

    ADDING CONTRIB/CUSTOM code docs


    1. Download code
    2. Create a project (module/theme)
    3. Create branch(es)
    4. Run cron to update

    NOTE: Its much easier to create a simple shell script to process the queue with Drush. See step 3.5 :    https://drupal.org/node/1516558

    documentation in the code

    DocBlock comments:

    • Explain your code for others 
      (or for yourself  in a month)

    • Get code hints in most IDE's

    • Make your code ready for API docs





    "If you come across core or 
     contrib code that is missing 
     comments, then open a critical
     bug on the issue queue. If 
     anyone complains, tell them to 
     talk to me..."
          -- @crell 

    (Larry Garfield - paraphrased)

    THE MAGIC OF DOXYGEN


    "Doxygen is a documentation generator, a tool for writing software reference documentation. The documentation is written within code, and is thus relatively easy to keep up to date. Doxygen can cross reference documentation and code, so that the reader of a document can easily refer to the actual code."


    http://en.wikipedia.org/wiki/Doxygen


    https://drupal.org/coding-standards/docs

    tips:

    1. "Always code as if the person who will maintain your code is a maniac serial killer that knows where you live"

    2. Start writing your comments & functions before you code

    3. Each function/method should do a single thing

    4. Run coder

    5. Develop an appreciation for beautiful code

    example


    hook_form_alter()

    homework

    (pick one)

    Setup a local APIdocs site for:
    • yourself
    • your team
    • a client
    • the community
    • a non-drupal PHP project

    questions

    Build your ownDrupal API site

    By Ron Northcutt

    Build your ownDrupal API site

    • 2,343