Jump to content



Photo
- - - - -

osCommerce Library - New Documentation Site


  • Please log in to reply
20 replies to this topic

#1 ONLINE   Harald Ponce de Leon

Harald Ponce de Leon

    Healthy Giraffe

  • Core Team
  • 4,893 posts
  • Real Name:Harald Ponce de Leon
  • Gender:Male
  • Location:Solingen, Germany

Posted 04 December 2012 - 01:33

Hi All..

An initial build of the new documentation site, titled osCommerce Library, has been pushed to Github and aims to replace our existing documentation sites (Confluence and the documentation section on the forum).

This is obviously built on our new framework to allow us to create a site that meets our requirements (integration) and to make writing documentation fun again. The content from the forum documentation section has already been migrated to it and will replace it as soon as the design and navigation has improved. After this the content from Confluence will be migrated over to finally be able to replace that as well.

The documentation content is now written in HTML files with the possibility of using template tags from the new framework to help make it easier writing complex HTML blocks.

The benefits of storing the documentation content in files and not in the database is it makes it really really easy to edit the HTML files in your favourite editor and push the changes to Github which the server can then pull and use instantly.

At first a Markdown implementation was being developed however the amount of work involved to produce nice looking output was not worth it when HTML could already be used which simplified things a lot. Styling is based on Bootstrap and styles can be customized where appropriate.

The documentation site organizes the documentation content as Books -> Chapters -> Pages. The structure and sort ordering is defined in a json file:

https://github.com/h...content_en.json

This makes it easy to add, remove, and reorder pages and chapters in a book. Each is identified via a code and to prevent conflicts of duplicate files, the HTML files are named in the following manner:

book_code-chapter_code-page_code.html ("-" separating each section)

This can be seen here:

https://github.com/h...line/Content/en

It might be better to split the long filenames into directories (eg, book_code/chapter_code/page_code.html) so this style may change.

Foreign languages are taken into account so the documentation can be translated into different languages. There is still some hardcoded "en" parts in the source code that will be updated. Please do not start translating as the documentation is outdated. Feel free to translate the release notes though.

The documentation site in its initial and current form can be reached at:

http://library.oscommerce.com

As a side note, this is one of the cool features of the framework where a site can have its own URL. Although http://www.oscommerc...dex.php?Library would be the original URL, it has its own address defined in the settings and the framework automatically detects this and uses it :) Some url rewrite magic is still needed though to support multiple languages with /en/, /de/, /fr/, etc.. in the url.

Please note that this is an early build and is still being worked on. The design and navigation will definitely improve and it is also planned to index the documentation content into a database to allow searching.

The flexibility of the new site also allows us to use wkhtmltopdf in backend scripts to produce PDF formats of the documentation to include in releases.

Feedback welcome! :)

What are the thoughts of the initial code?
Should the HTML filenames be split into directories for a cleaner structure?
Should foreign languages follow the english layout (table of contents) or have their own freestyle layout?
Should a rating or comment system be added?
Harald Ponce de Leon

#2   foxp2

foxp2

    strong as a Twig

  • Banned
  • 310 posts
  • Real Name:Laurent
  • Gender:Male
  • Location:France

Posted 04 December 2012 - 11:46

Should foreign languages follow the english layout (table of contents) or have their own freestyle layout?


Because we'll have our own website, i prefer to get our own documentation (based on yours, of course), hosting on our servers.

Should a rating or comment system be added?


imo, forum is the right place to doit. i don't want to manage the polluting comments ... /wacko.png' class='bbc_emoticon' alt=':wacko:' />
-------------------

#3 ONLINE   Harald Ponce de Leon

Harald Ponce de Leon

    Healthy Giraffe

  • Core Team
  • 4,893 posts
  • Real Name:Harald Ponce de Leon
  • Gender:Male
  • Location:Solingen, Germany

Posted 04 December 2012 - 18:22

The design layout has been updated to a full page width layout! The navigation is now taken care of with a combination of navigation bar and breadcrumb element.
Harald Ponce de Leon

#4 ONLINE   burt

burt

    Vanquisher of Demons

  • Community Team
  • 9,994 posts
  • Real Name:G Burton
  • Gender:Male
  • Location:UK/DEV/on

Posted 04 December 2012 - 18:33

ratings could be useful?
not comments though as that leads to all sorts of problems (forum is better used for this).
IF YOU MAKE A POST REQUESTING HELP...please state the exact version of osCommerce that you are using. THANKS
 
Big Bang Templates for 2.3 osCommerce - 2.3.1 > 2.3.4 - Buy One, Get One Free
 
--
Making your osCommerce better, one module at a time - get in touch.

#5 ONLINE   Harald Ponce de Leon

Harald Ponce de Leon

    Healthy Giraffe

  • Core Team
  • 4,893 posts
  • Real Name:Harald Ponce de Leon
  • Gender:Male
  • Location:Solingen, Germany

Posted 04 December 2012 - 18:41

Using git submodules it would also be possible to link in directories containing documentation that Add-Ons could use.

It would be great for developers to be able to push a button to refresh the documentation on the website (pull the latest documentation from github), however it would pose security issues as the content is HTML/Javascript - will need to look into it so malware is not injected into the website.
Harald Ponce de Leon

#6 ONLINE   burt

burt

    Vanquisher of Demons

  • Community Team
  • 9,994 posts
  • Real Name:G Burton
  • Gender:Male
  • Location:UK/DEV/on

Posted 04 December 2012 - 18:46

@Harald Ponce de Leon - it sounds like you are having too much fun /wink.png' class='bbc_emoticon' alt=';)' />
IF YOU MAKE A POST REQUESTING HELP...please state the exact version of osCommerce that you are using. THANKS
 
Big Bang Templates for 2.3 osCommerce - 2.3.1 > 2.3.4 - Buy One, Get One Free
 
--
Making your osCommerce better, one module at a time - get in touch.

#7   altoid

altoid
  • Community Sponsor
  • 1,050 posts
  • Real Name:Steve
  • Gender:Male
  • Location:Hollidaysburg, Pennsylvania

Posted 05 December 2012 - 01:28

i've already taken a couple of my shops up to 2.3.3, so i've already done what's on here: http://library.oscom...s&v2_3_3#upgtop

maybe it's just my way of doing these things but what would be handy would be to be able to download the entire contents of the page to an editable pdf file. where upon doing an update i could make notes on each change, issues that came up when doing the update (such as other add ons that already affected the code) and so on.

for example as i go through the upgrades i would note at each step "done" so if i came back later i'd have a reminder.

as well, if an update was a problem for me due to another add on already installed and changing the existing code, i would notate that. such as quantity tracking pro code effected some existing code so when going from 2.3.2 to 2.3.3 the instructions did not apply for my situation.

my point is by having the editable pdf i would have documentation so what when i tackle 2.3.4, i may refer to my note on the 2.3.3 upgrade and refresh my memory on why i did this or that.

hope that all makes sense.

thanks
I am not a professional webmaster or PHP coder by background or training but I will try to help as best I can.
I remember what it was like when I first started with osC. It can be overwhelming.
However, I strongly recommend considering hiring a professional for extensive site modifications, site cleaning, etc.
There are several good pros here on osCommerce. Look around, you'll figure out who they are.

#8 ONLINE   Harald Ponce de Leon

Harald Ponce de Leon

    Healthy Giraffe

  • Core Team
  • 4,893 posts
  • Real Name:Harald Ponce de Leon
  • Gender:Male
  • Location:Solingen, Germany

Posted 07 December 2012 - 22:53

@altoid

The flexibility of the new site also allows us to use wkhtmltopdf in backend scripts to produce PDF formats of the documentation to include in releases.


;)

Regarding Add-Ons, hopefully we'll have a working example ready over the weekend with how documentation for Add-Ons can be managed. The format would first follow:

Add-Ons -> Company -> Add-On

for example,

Add-Ons -> osCommerce -> PayPal Express
Add-Ons -> osCommerce -> PayPal Standard
Add-Ons -> osCommerce -> SagePay Server

As the Library site currently only allows 3 levels (Book -> Chapter -> Pages), documentation for Add-Ons would be written in a single page.

Additionally, it is possible to add an information page to a chapter (the company page) to display the copyright notice/license the author has chosen (strict copyright, creative commons, public domain, ..) - the minimum requirement would be to allow reproduction for personal use and to allow us to publish the documentation on the Library site.

The Add-Ons documentation would be handled by another Site Application to optimize its functionality which is more flexible than how the core documentation is managed (by the "Online" site application).

As soon as this is all ready it will be officially announced!
Harald Ponce de Leon

#9 ONLINE   Harald Ponce de Leon

Harald Ponce de Leon

    Healthy Giraffe

  • Core Team
  • 4,893 posts
  • Real Name:Harald Ponce de Leon
  • Gender:Male
  • Location:Solingen, Germany

Posted 07 December 2012 - 22:59

One more issue: images! The current location of the documentation disallows public access from the web server and it would be ideal for Add-On documentation to be self contained directories of html files and images. To be able to use git submodules and not need a separate directory for images, the Asset directory containing the documentation html files would have to be moved to the same directory location where index.php is (so outside of osCommerce/OM). (or to public/ but that's not the right place for it either)

A htaccess file could be added to block requests to .html files but there really isn't a need for that.
Harald Ponce de Leon

#10 ONLINE   Harald Ponce de Leon

Harald Ponce de Leon

    Healthy Giraffe

  • Core Team
  • 4,893 posts
  • Real Name:Harald Ponce de Leon
  • Gender:Male
  • Location:Solingen, Germany

Posted 16 December 2012 - 02:22

Cool! I just pushed out some updates to the Library repository that adds support for Add-Ons documentation via git submodules!

The whole Asset directory containing the documentation html files and images has been moved to the public/sites/Library/Asset directory so images can be served and the documentation files reside in self contained directories. A .htaccess file exists to block access to all files apart from jpg, gif, and png images (the current .htaccess version does not work and needs to be updated). This can be seen here:

https://github.com/h...s/Library/Asset

What's interesting now is the Add-Ons documentation are now linked from external git repositories via git submodules. This can be seen here:

https://github.com/h...kage/Content/en

I've created library_paypal and library_sage_pay repositories holding the documentation for the PayPal and Sage Pay payment modules, and is linked to in the Asset/Package/ directory which the Library site automatically detects and serves.

Now developers can create their own git repositories for the documentation to their Add-Ons which can then be linked to on the website_library repository to serve through the Library site. Awesome!

Documentation will soon be added to help developers with the process of putting documentation together. When this system matures and developers start to using it, a new documentation moderator group will be formed and be given access to administrate the GitHub repository pull requests and to update the content the Library site serves.

The changes are also live on the Library site!
Harald Ponce de Leon

#11 ONLINE   Harald Ponce de Leon

Harald Ponce de Leon

    Healthy Giraffe

  • Core Team
  • 4,893 posts
  • Real Name:Harald Ponce de Leon
  • Gender:Male
  • Location:Solingen, Germany

Posted 16 December 2012 - 02:44

There's also a new Wiki section for community contributed documentation (eg, tips and tricks). This has a more liberal Creative Commons copyright terms to better fit community additions compared to the terms of the core documentation.

This is a much better solution for tips and tricks that are currently posted to the forum where they can be kept up to date on the Library site and be linked to and discussed on the forum.
Harald Ponce de Leon

#12   foxp2

foxp2

    strong as a Twig

  • Banned
  • 310 posts
  • Real Name:Laurent
  • Gender:Male
  • Location:France

Posted 16 December 2012 - 19:55

Hi Harald,
i'm working on FAQ website for osCommerce France, based on your framework ( to replace our old faq : http://www.oscommerce-fr.info/faq/).
you might be interested by this project ?
-------------------

#13 ONLINE   Harald Ponce de Leon

Harald Ponce de Leon

    Healthy Giraffe

  • Core Team
  • 4,893 posts
  • Real Name:Harald Ponce de Leon
  • Gender:Male
  • Location:Solingen, Germany

Posted 18 December 2012 - 20:37

@ foxp2 , the Library site supports multiple languages. What do you think of adding and maintaining the French documentation on it?
Harald Ponce de Leon

#14   foxp2

foxp2

    strong as a Twig

  • Banned
  • 310 posts
  • Real Name:Laurent
  • Gender:Male
  • Location:France

Posted 18 December 2012 - 21:47

@Harald Ponce de Leon

i've seen you're planning to do it from the start.
since the beginning of 2012, i'm trying to stay the course.
i'm the first to say that documentation is really important (that's why i've done it for the francophone community)
But in my community, i'm just only a moderator.
I'd have to go back to consult my team before to take a decision.
i hope you'll understand my caution.
-------------------

#15 ONLINE   Harald Ponce de Leon

Harald Ponce de Leon

    Healthy Giraffe

  • Core Team
  • 4,893 posts
  • Real Name:Harald Ponce de Leon
  • Gender:Male
  • Location:Solingen, Germany

Posted 20 December 2012 - 02:11

Hi All..

A new {toc} template tag has been added that automatically generates a table of contents list for the current page being read. An example is at:

http://library.oscom...ntation

It automatically builds a list from h2-h6 headings and automagically links to their position on the page without the need to use anchors or heading IDs. If a heading has a stylesheet class of "ignore" it does not get added to the table of contents list.

I consider that to be quite :cool_tag: :thumbsup:

A minor fix needs to be worked on for long table of contents lists, as can be seen here:

http://library.oscom...se_notes&v2_3_3
Harald Ponce de Leon

#16   foxp2

foxp2

    strong as a Twig

  • Banned
  • 310 posts
  • Real Name:Laurent
  • Gender:Male
  • Location:France

Posted 26 December 2012 - 11:55

@Harald Ponce de Leon

@ foxp2 , the Library site supports multiple languages. What do you think of adding and maintaining the French documentation on it?


work in progress : https://github.com/f...website_library
-------------------

#17   foxp2

foxp2

    strong as a Twig

  • Banned
  • 310 posts
  • Real Name:Laurent
  • Gender:Male
  • Location:France

Posted 29 December 2012 - 13:23

@Harald Ponce de Leon
opening two issues : https://github.com/haraldpdl/website_library/issues
-------------------

#18   foxp2

foxp2

    strong as a Twig

  • Banned
  • 310 posts
  • Real Name:Laurent
  • Gender:Male
  • Location:France

Posted 29 December 2012 - 22:11

@Harald Ponce de Leon

Hi Harald,


Essentially, with two exceptions (submitted on the above post), the translation of website library is fully completed.
included :
wiki + the osCommerce 3 book + the osCommerce 2.3 book.
a pull request is pending : https://github.com/haraldpdl/website_library/pulls

Regards.
-------------------

#19   Gergely

Gergely

    Action Hero

  • Community Team
  • 1,256 posts
  • Real Name:Gergely Tóth
  • Gender:Male
  • Location:Budapest

Posted 10 August 2014 - 18:26

Hi @Harald Ponce de Leon,

 

I have an error to do symlinks on windows system. I suggest to implement into the installation documents the following :thumbsup:

ln: creating symbolic link `Website' to `../../../../../oscommerce_website/osCom
merce/OM/Custom/Site/Website': Permission denied
mkdir oscommerce\osCommerce\OM\Custom\Site
cd oscommerce\osCommerce\OM\Custom\Site
mklink /D Website ..\..\..\..\..\oscommerce_website\osCommerce\OM\Custom\Site\Website
mklink /D Admin ..\..\..\..\..\oscommerce_website\osCommerce\OM\Custom\Site\Admin
mklink /D _skel ..\..\..\..\..\oscommerce_website\osCommerce\OM\Custom\Site\_skel
cd ..
mklink /D Exception ..\..\..\..\oscommerce_website\osCommerce\OM\Custom\Exception
cd ..
mkdir External
mklink /D External\simplepie_1.3.1.mini.php ..\..\..\oscommerce_website\osCommerce\OM\External\simplepie_1.3.1.mini.php
cd ..\..\public\sites
mklink /D Website ..\..\..\oscommerce_website\public\sites\Website
cd ..\external
mklink /D bootstrap ..\..\..\oscommerce_website\public\external\bootstrap
mklink /D less ..\..\..\oscommerce_website\public\external\less

this is very complicated installation...


I have found that External dir didnt created in symlink (mkdir) command. This could be an issue.

Regards,

Gergely
 


Edited by Gergely, 10 August 2014 - 18:33.

some rewrites :-


#20   Gergely

Gergely

    Action Hero

  • Community Team
  • 1,256 posts
  • Real Name:Gergely Tóth
  • Gender:Male
  • Location:Budapest

Posted 10 August 2014 - 18:58

The Library symlinc creation in windows enwiroment

cd oscommerce\osCommerce\OM\Custom\Site
mklink /D Library ..\..\..\..\..\website_library\osCommerce\OM\Custom\Site\Library
cd ..\..\..\..\public
mklink /D external\prettify ..\..\..\website_library\public\external\prettify
mklink /D sites\Library ..\..\..\website_library\public\sites\Library

some rewrites :-