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
-
Create Drupal site
- Install modules and libraries
- Set-up code repositories
- Set-up API module to index the code
(for each project and branch) - Run cron to index the sites
How to - the short(er) way
DrupalAPI Install Profile :
- Install with profile
- Update code
- 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
- Download code
- Create a project (module/theme)
- Create branch(es)
- 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
- Download code
- Create a project (module/theme)
- Create branch(es)
- Run cron to update
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
tips:
-
"Always code as if the person who will maintain your code is a maniac serial killer that knows where you live"
- Start writing your comments & functions before you code
- Each function/method should do a single thing
- Run coder
- 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