I know there is way to copy static files via jsdoc, for images as example.
Is there a way to "extend" the generated template via markdown or html files that integrate into the "look & feel" of the used theme?
I know you can include one markdown file as "landing page", but i wonder if its possible to add more pages/files.
Why im asking this?
Because i want to generate the documentation out of my source code and add then some additional pages which describe the workflow of my application or the behavior of some components.
Doing this in a single markdown document & that as "landing page" seems not a good solution.
I cant imagine that there exist not a "read to use" solution.
I just want a nice & complete documentation of my application which includes stuff from the source code and additional pages.
Any hint is welcome.
Thanks in Advance.
So I've began working with .cfm files recently at work, currently my assignment is to modify and update webpages to be more suited to mobile devices and tablets. Now, being relatively new to ColdFusion, I've been having a bit of trouble with how multiple .cfm files are used within a server to create a single webpage. Because of this, I've had issues with finding where specific sections of HTML are located, be it something as where a simple tag is, or where a call to another .cfm, javascript, or .css file may be. Is there anyway to find the origin of certain code without having to skim through hundreds of different files?
If you are working on your code on a local webserver on your computer (i.e. not a production site) then you can enable ColdFusion's debugging output.
Documentation for the ColdFusion Administrator debugging options are here: ColdFusion Administrator Debugging
You will want to enable Enable Request Debugging Output and turn on Report Execution Times. When you browse to the page, ColdFusion will give you a list of all files that ColdFusion used to render that page (with how long each file took) appended to the bottom of the page.
Otherwise, any good IDE/Editor (CFBuilder, SublimeText, NotePad++ etc) will be able to search across files.
I would suggest downloading the code from your server to a local drive. From there you can search using an IDE (ColdFusion Builder, Dreamweaver, etc) or a good text editor that can search multiple files at once. I personally use ColdFusion Builder 3 and Notepad++.
Multiple cfm files are put together into a single page usually by using the cfinclude tag, so that would be a good starting point for your search. There are other methods to include different pages into a single page but cfinclude is probably the most common one. BUT, if the programmer used cfscript instead of cfml, look for the include function instead.
Adobe documentation on the cfinclude tag can be found at https://wikidocs.adobe.com/wiki/display/coldfusionen/cfinclude.
I've been slowly weening myself off of Dreamweaver and using other editors like SublimeText and Espresso. But there are two features that are lacking in those editors that I still find the need to use Dreamweaver for:
1.) Find and Replace within entire current local site.
2.) Update links when a page is saved within another directory. For example, if you rename, or re-save a file that is open within another directory, Dreamweaver will ask you to update the links. This will then make sure that if the file is moved or saved to another directory it will update any links within the HTML for stylesheets, images, navigation, etc.
Does any know of any other apps or tools that might be able to accomplish those actions without having to crack open Dreamweaver?
Any input is greatly appreciated. Thanks!
The Sublime Text plugin 'Side Bar Enhancements' has Search/Replace entire project functionality. Doesn't handle update links across files (that i've found)
PHPStorm may handle the second question.
I have many source/text file, say file.cpp or file.txt . Now, I want to see all my code/text in browser, so that it will be easy for me to navigate many files.
My main motive for doing all this is, I am learning C++ myself, so whenever I learn something new, I create some sample code and then compile and run it. Also, along these codes, there are comments/tips for me to be aware of. And then I create links for each file for easy navigation purpose. Since, there are many such files, I thought it would be easy to navigate it if I use this html method. I am not sure if it is OK or good approach, I would like to have some feedback.
What I did was save file.cpp/file.txt into file.html and then use pre and code html tag for formatting. And, also some more necessare html tags for viewing html files.
But when I use it, everything inside < > is lost
eg. #include <iostream> is just seen as #include, and <iostream> is lost.
Is there any way to see it, is there any tag or method that I can use ?
I can use regular HTML escape code < and > for this, to see < > but since I have many include files and changing it for all of them is bit time-consuming, so I want to know if there is any other idea ??
So is there any other solution than s/</< and s/>/>
I would also like to know if there any other ideas/tips than just converting cpp file into html.
What I want to have is,
in my main page something like this,
tip1 Do this
tip2 Do that
When I click tip1, it will open tip1.html which has my codes for that tip. And also there is back link in tip1.html, which will take me back to main page on clicking it. Everything is OK just that everything inside < > is lost,not seen.
Thanks.
You might want to take a look at online tools such as CodeHtmler, which allows you to copy into the browser, select the appropriate language, and it'll convert to HTML for you, together with keyword colourisation etc.
Or, do like many other people and put your documentation in Doxygen format (/** */) with code samples in #verbatim/#endverbatim tags. Doxygen is good stuff.
A few ideas:
If you serve the files as mimetype text/plain, the browser should display the text for you.
You could also possibly configure your browser to assume .cpp is text/plain.
Instead of opening the files directly in the browser, you could serve them with a web server than can change the characters for you.
You could also use SyntaxHighlighter to display the code on the client side using JavaScript.
It is pretty much essential that somewhere along the line you use a program to prevent the characters '<>&' from being (mis-)interpreted by your browser (and expand significant repeated blanks into '` '). You have a couple of options for when/how to do that. You could use static HTML, simply converting each file once before putting it into the web server document hierarchy. This has the least conversion overhead if the files are looked at more often than they are modified. Alternatively, you can configure your web server to server the pages via a filter program (CGI, or something more sophisticated) and serve the output of that in lieu of the file. The advantage is that files are only converted when needed; the disadvantage is that the files are converted each time they are needed. You could get fancy and consider a caching solution - convert the file on first demand but retain the converted file for future use. The main downside there is that the web server needs to be able to write to where the converted file is cached - not necessarily a good idea for security reasons. (A minimalist approach to security requires the document hierarchy to be owned by and only writable by one user, say webmaster, and the web server runs as another user, say webserver. Now the web server cannot do any damage because it cannot write anywhere in the document hierarchy. Simple; effective; restrictive.)
The program can be a simple Perl script or a simple C program (the C source for webcode 1.3 is available here).
IMPORTANT: The accepted answer was accepted post-bounty, not necessarily because I felt it was the best answer.
I find myself doing things over and over when starting new projects. I create a folder, with sub-folders and then copy over some standard items like a css reset file, famfamfam icons, jquery, etc.
This got me thinking what the ideal starting template would be. The reason I'm asking is that I'm going through once again and am wondering what I should include in my template so that I don't have to go back in the future and do this all over again with every new site I start.
What I currently have follows:
Project Template Folder
index.html -- XHTML 1.0 Strict Doctype. Meta Tags. CSS/js Files Referenced.
css/
default.css -- Empty. Reserved for user-styles.
960/ -- 960 Grid System for CSS Layouts.
960.css
reset.css
text.css
js/
default.js -- Empty. Reserved for user-scripts.
jQuery/ -- Light-Weight Javascript Framework
jquery-1.3.1.min.js
img/
famfamfam/ -- Excellent collection of png icons
icons/
accept.png
add.png
...etc
I have a similar structure and naming convention but for CSS, I use BluePrint which I find is more extensible. Also prefer jQuery having recently switched from prototype. In addition I have a common.js file that is an extension with custom functions for jQuery.
A /db/ folder with .sql files containing schema definitions. A /lib/ folder for common middle-tier libraries.
I will also have a /src/ folder which will sometimes have raw files such as Photoshop templates, readme's, todo lists etc.
If you have a lot of projects with a lot of static content in common (e.g. jquery, css framework, etc) make yourself a media server to serve all these. Then, instead of creating a bunch of folder structure from a "template" all you do is include the right files in your project's html. If you really want a template, your template becomes one html file instead of a directory structure.
This also gives you an easy way to update the static media for your sites (e.g. moving to the next version of 960). you only have to do it in one place. Of course, you still have to make sure that your updates don't break existing sites! :)
You can make the scheme a bit more complicated if certain projects have overlapping needs but are different from others. Just have a directory at the top level of the server for each setup and to each setup corresponds one html "template". The main idea is to have to deal with only one copy of everything that is common.
You can certainly do this on a small VM (e.g. linode) for $20/mo or a virtual web-server on your current web server. You don't really need a server, for that matter, you just need a folder. However, I think you can have some significant performance gains by having a dedicated media servers. I'd recommend using a fine-tuned apache or nginx for this purpose.
As for site-specific static files, it is also a good idea that they live on the media server and the directory structure would probably be exactly what you have, but they would/should be empty directories.
My web development framework sits in a git repository. Common code, such as general purpose PHP classes gets developed in the master branch. All work for a particular website gets done on a branch, and then changes that will help in future work get merged back into master.
This approach works well for me because I have full revision control of all the websites, and if I happen to fix a bug or implement a new feature while working on a branch I can do the merge, and then everything benefits.
Here's what my template looks like:
/
|-.htaccess //mod_rewrite skeleton
|-admin/ //custom admin frontend to the CMS
|-classes/ //common PHP classes
|-dwoo/ //template system
|-config/ //configuration files (database, etc)
|-controllers/ //PHP scripts that handle particular URLs
|-javascript/
|-tinyMCE/
|-jquery/
|-modules //these are modules for our custom CMS
|-news/
|-mailing_list/
|-others
|-private/ //this contains files that won't be uploaded (.fla, .psd, etc)
|-.htaccess //just in case it gets uploaded, deny all
|-templates/ //template source files for dwoo
I use a similar layout, but with one major exception: all of these directories live under a top-level media/ directory. This is for a few reasons:
This directory is rsync'd to two other servers which handle all of the static media requests.
Having multiple hosts allows some browsers to make more parallel requests for support files.
The media/ directory has its own .htaccess file which strips off a psuedo directory from the path which is the date-time last modified of the image (or whatever).
A custom template tag (I have used this with 2 Django projects, but you could do it in PHP, etc.) generates urls which a) semi-randomly choose one of the media servers, b) add the time-based pseudo directory to the path, and c) give the object an Expires time of now + 10 years.
I think the structure is good. The addition of a few other folders depends on what type of work you are completing.
For freelancing and the like, the addition of PSD folders, client comments would be a nice addition.
A very MS skewed view, but my SOP right now is along the lines of:
documentation/
architecture/ (what you might call code documentation)
communications/ (important client docs)
spec/
whitepapers/
graphics/
*.psd
source/
com.mycompany.projectname.solutionA/
com.mycompany.projectname.solutionB/
com.mycompany.projectname.solutionC/
com.mycompany.projectname.solutionX/ (project in the business sense here)
businesslogic/
*.cs (or whatever)
(further projects - in the visual studio sense)
site/
handlers/ (rarely do I use actual .html these days)
modules/
resources/
img/ (pngs jpegs, gifs whatever)
skin/
icons/
backgrounds/
js/ (compressed when published)
library/ (standard code)
common/ (app specific code)
*.js (app specific code, hopefully nil)
css/
skinX/ (even if there is only "default")
extension.css
base.css
transforms/(always hidden from public by config or build process)
*.xslt
unittests/
mocks/
testmain.cs (or whatever)
thirdparty/
dependencies
I definitely love the idea of having a skeleton template folder like this, but if you use a few different technologies, definitely pay close attention to the structure. My VB.net folder structure has a totally different setup compared to PHP. It sounds like common sense, but I have seen people approach both the same way.
At work we use Code Igniter as a PHP framework for our web applications and have created a new project template which does exactly that: Simple directory structure, Blueprint CSS, jQuery and the Code Igniter application folder, filled with a couple of commonly used libraries (Authentication, some speciales models for often used databases...).
The main motto here is: It's always easier to delete components than to add them. So fill your template up.
(And when I'm starting a new project in my spare time I sorely miss that template...)
I think what you have here is great.... What you've listed is of course all about the public front end of your app. My only addition to this, is to keep all your backend code and source out of the public web space if possible, as the less things you have in the public space, the more secure your app is.
So I'd suggest you take your entire tree, and put it in:
httpdocs/(all you had in your project template folder)
then put all your backend code (e.g. php libraries, sql files, etc) in adjacent subdirectories:
httpdocs/(all you had in your project template folder)
phplibs/
sql/
etc.
And, even for your front end stuff, make sure you don't copy in any example files that may come with your front end libraries, as the examples themselves may have security problems that would allow people to XSS or otherwise compromise your site.
I have been using the following setup for a while now with great results:
/site: This is where my actual working website will live. I'll install my CMS or platform in this directory after the templates are created.
.htaccess (basic tweaks I usually find myself enabling anyway)
robots.txt (so I don't forget to disallow items like /admin later)
/source: Contains any comps, notes, documents, specifications, etc.
/templates: Start here! Create all static templates that will eventually need to be ported into the CMS or framework of /site.
/behavior
global.js (site-specific code; may be broken out into multiple files as needed)
/media: Images, downloadable files, etc. Organized as necessary
/style: I prefer modular CSS development so I normally end up with many stylesheet for each unique section of the website. This is cleaned up greatly with Blender - I highly recommend this tool!
behavior.css (any styling that requires a JS-enabled browser)
print.css (this eventually gets blended, so use #media print)
reset.css (Eric Meyer's)
screen.css (for #media screen, handheld)
/vendor: all 3rd party code (jQuery, shadowbox, etc.)
Blendfile.yaml (for Blender; see above)
template.html (basic starting template; can be copied and renamed for each unique template)
I like OPs as a default start point. your standard template should err on simplicity, with the ability to add complexity only if it's needed.
one addition:
/robots.txt