Coder Social home page Coder Social logo

silverstripe / silverstripe-docsviewer Goto Github PK

View Code? Open in Web Editor NEW
20.0 16.0 24.0 1.09 MB

Documentation generator that powers doc.silverstripe.org and your own projects

License: BSD 3-Clause "New" or "Revised" License

PHP 74.94% CSS 15.78% JavaScript 3.56% Scheme 5.72%

silverstripe-docsviewer's Introduction

Documentation Viewer Module

ABANDONED

This package is abandoned. See silverstripe/doc.silverstripe.org instead.

Build Status

Maintainer Contact

Requirements

These are pulled in via Composer.

  • SilverStripe 3.1
  • Parsedown and Parsedown Extra.

Summary

Reads markdown files from a given list of folders from your installation and provides a web interface for viewing the documentation. Ideal for providing documentation alongside your module or project code.

A variation of this module powers the main SilverStripe developer documentation and the user help websites.

For more documentation on how to use the module please read /docs/Writing-Documentation.md (or via this in /dev/docs/docsviewer/Writing-Documentation in your webbrowser)

Installation

composer require "silverstripe/docsviewer" "dev-master"

Usage

After installing the files via composer, rebuild the SilverStripe database..

sake dev/build

Then start by viewing the documentation at yoursite.com/dev/docs.

If something isn't working, you can run the dev task at yoursite.com/dev/tasks/CheckDocsSourcesTask to automatically check for configuration or source file errors.

Out of the box the module will display the documentation files that have been bundled into any of your installed modules. To configure what is shown in the documentation viewer see the detailed documentation.

For more information about how to use the module see each of the documentation

* [Configuration](docs/en/configuration.md)
* [Markdown Syntax](docs/en/markdown.md)
* [Syntax Highlighting](docs/en/syntax-highlighting.md)
* [Publishing Static Files](docs/en/statichtml.md)

License

See LICENSE

silverstripe-docsviewer's People

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

silverstripe-docsviewer's Issues

Inline code not working in div with class "info"

Go to http://doc.silverstripe.org/en/developer_guides/configuration/configuration/
search "The name of the files within the applications", the words _config, email.yml and others in the inline code are not in the inline format. The source is as below:

<div class="info" markdown="1">
The name of the files within the applications `_config` directly are arbitrary. Our examples use 
`mysite/_config/app.yml` but you can break this file down into smaller files, or clearer patterns like `extensions.yml`, 
`email.yml` if you want. For add-on's and modules, it is recommended that you name them with `<module_name>.yml`.
</div>

However, it works for class "alert":

<div class="alert" markdown="1">
Due to YAML limitations, having multiple conditions of the same kind (say, two `EnvVarSet` in one "Only" block)
will result in only the latter coming through.
</div>

User edits created commits to underlying git repo

Should be able to provide a commit message.

Allows bigger doc contributions from technical writers, the repo could then be cherry picked/merged to capture more incremental documentation contributions.

Alternatives to discuss for targeted documentation discussion

I don't think discuss really cuts the mustard, especially with documentation issues, updates and discussion. I would like to spark up a discussion about how we could improve this on our documentation. Discuss also shows old threads which are (sometimes) no longer relevant to a version etc.

One example of targeted documentation discussion is on medium (https://medium.com/php-development/64eb28781489) where a message is posted to a paragraph and can be viewed while you are reading the content rather then down the bottom of the page.

It would also be handy to mark these issues/comments once they are resolved by a community member rather then having them hang around.

Linking to 4.0 (master) API docs

While reviewing the Silverstripe 4 documentation I came across a link that is supposed to lead to a page on the Silverstripe 4 api docs.

The link in question tries to link to i18n::set_locale() with [api:i18n::set_locale()], but this link is invalid as the api docs for this class in 4.0 are under master, as opposed to 4.

Further digging has revelaled that the documentation is littered with these broken links

Upgrade to SilverStripe 4 (or don't?)

Before spending a lot of time on upgrading this module to SS4, we should resolve the discussion around moving doc.silverstripe.org to a third party documentation service: silverstripe/doc.silverstripe.org#157

While I acknowledge that docsviewer is used in other contexts, it significantly lowers our need to upgrade it if we're not using it on doc.ss.org. I see docsviewer (and the related maintenance around doc.ss.org) as a moderate distraction for SS Ltd, which could be better spent elsewhere. Our Markdown isn't that special :D

Page sorting limitation

At the moment page sorting is done by prefixing a document with a number. If you ever want to change the order of pages or introduce a new page between existing ones you may have to rename several files which could complicate the git history and make merges difficult.

Wondering if instead of prefixing the filenames, we have a 'priority' field in addition to the 'title' and 'summary' field in each file, which could use positive and negative decimals to allow a lot more flexibility in sorting.

Prev/next navigation for pages in a folder

At the bottom of each content page, you should be able to go to the next/previous topic (in the same folder).

Paul has already added CSS for the following markup:

Rather than "previous" labels it should show the actual page title.

On the first page, we could link to the index, or "top"/up one level, on last page to the index page of next folder. Thats less important though.

More helpful 404 page (integrated search/suggestions box)

See attached screenshot of Paul's mockup, with this markup (CSS already in place):

We're sorry…

The page you are looking for might have moved, no longer exists or is not currently available.

Perhaps you could…

return to the homepage or try searching.

Search results for similar/related phrases
                    <div class="warningBoxBottom">

                        <ul>
                            <li><a href="#">Report a missing link</a></li>
                            <li><a href="#">Report a bug or a concren</a></li>
                        </ul>
                    </div>
                </div>

http://open.silverstripe.org/attachment/ticket/6344/Screen%20shot%202011-01-13%20at%208.33.33%20PM.png

Nicer, more hackable search URL

Before: home/DocumentationSearchForm?Search=bbcode&action_results=Search After: /?q=bbcode

Should be possible by adding a check in index(), and overwriting the form action :) Not sure how to get rid of the button, perhaps we can do a redirect in index() as well (which would slow down search, so not ideal)

Sitemap.xml generation to prioritise latest stable docs

I find that google searches like silverstripe file often return results for outdated versions of SilverStripe, even going back to 3.0.

I wonder if this module could automatically generate a sitemap.xml file that sets the priority of the stable channel to high, and unreleased and old versions to low? Hopefully that would signal to Google that they should surface e.g. api.silverstripe.org/en/3.6/class-File.html ahead of api.silverstripe.org/en/3.1/class-File.html.

Permisions for non-admins

I'm currently using the docsviewer for craeteing documention for content editors, however the docs can only be seen if the user has full admin rights. Is there a way to allow other user groups to view it?

Use markdown metadata for generating title of the page.

We cant reliably convert filenames into proper english grammar, e.g. "Ingo's awesome changes" would be named "ingos-awesome-changes.md", which currently translates back into "Ingos Awesome Changes", losing the apostrophe and proper capitalization.

We might look into Markdown metadata for this purpose as well, in the form of:

Title: Ingo's awesome changes
Author: Ingo Schommer

Actual title of the page

body body body

Better search summary text

Currently it takes $Content, with all HTML stripped off. This means that the <h1> will be seamlessly connected to the first paragraph, which reads very werid, for example:

"Email Sending SilverStripe?'s test system has built-in support for testing emails sent using the Email class. How it works For this to work, you need to send emails using the Email class, which is g..."

"Forms Introduction Form is the base class of all forms in a sapphire application. Forms in your application can be created either by instantiating the Form class itself, or by subclassing it. Insta..."

Use SimpleXML to extract the first <p> tag, but careful with performance - ideally we cache this as a new property on indexing time rather than computing dynamically.

Documentation index should respect versions

Currently this displays everything for every version of documentation (if using the multiversions).

This ideally would return the index for the currently selected version of the documentation and display the select version interface.

API Links to class methods and properties are broken.

Examples: in the docs

(i) [api:DataObjectSet->populateDefaults()] is a 404. In the rendered page one sees that it is selecting the docs version being viewed (2.4,3.0,3.1, etc...) and the module. However, a closing ")" on the method is missing.

(ii) [api:DataObject::$defaults] goes to master when it should select the docs version being viewed.

Related ? /issues/37

default version number cannot be directly accessed

for example if my version 3.1 is default I can access this via site/en/ and not site/en/3.1/ - which makes permalinks to certain documentation for versions a pain point. Suggest both should be accessable with the default /en/ setting a canonical meta tag to the version perhaps?

All [api] shortcode links are broken

Since we've moved to major version branches e.g. 4.x and 3.x, the version passed into the API website search URL is 4 or 3.

SS4 docs: The 4 branch doesn't exist yet, and could temporarily be changed to "master", although this could also be handled here in the API site code which might be prefereable.

SS3 docs: Currently the SS3 docs are passing 3 as the branch name, which isn't valid for the API site as it looks at minor versions. Otherwise, the version should be passed in as the stable minor version. The way the docs site is structuring it with major versions only, the stable minor is not available. This could also be handled temporarily with an htaccess redirect in api.silverstripe.org, or we could add another configuration parameter like ApiLinkBranch: 3.6 for example to docsviewer configuration.

Lastly, for namespaced API shortcode references, we need to convert to dot notation to match the API search format, e.g. \SilverStripe\ORM\DataExtension -> SilverStripe.ORM.DataExtension. This would be changed here.


Another alternative to the minor version branching mentioned above is that the API site could do a similar move as docs.ss (and soon userhelp.ss) and move to major version API docs only: 4.x and 3.x. Thoughts on this?


Related issues:

"All" page should only list an item once for the stable version

Example:

Duplicated titles

Given that we are viewing /en/all and no version is implied by the URL, the docs viewer currently displays every topic title for every version. This results in many duplicated titles/versions.

In this instance should we assume the stable version, and use that to list the topic titles just once?

cc @tractorcow

Create "edit" buttons for doc.silverstripe.org

So, strictly speaking this will be a change for doc.silverstripe.org but I think that it would be best implemented as a module feature.

We have documentation, for example at:
http://doc.silverstripe.org/framework/en/trunk/misc/contributing.md

There is already an edit link for this page at:
https://github.com/silverstripe/sapphire/edit/3.0/docs/en/misc/contributing.md

I would like for us to have an "edit" button on our doc pages, pointing at this link. GitHub will take care of the rest.

Prev/Next Links at Bottom missing dev/docs

The Prev/Next buttons at the bottom of the page return a link relative to site root:

http://mysite.com/en/documentation/sub_doc/sub_doc/
instead of
http://mysite.com/dev/docs/en/documentation/sub_doc/sub_doc/

All other links on the page are fine.

Manual ordering of pages and folders

Currently the main navigation has "Changelog" as the first element, because it happens to start with "C". Its also the least important element, much less so than "Tutorials". We need manual indexing, through Markdown metadata:

Title: Tutorials
Order: 1
To order a folder, the metadata would need to be placed in the contained index.md

(From http://open.silverstripe.org/ticket/6345)

docsviewer doesn't appear to work with SS3.0.5

I installed a standard SS3.0.5 site and then add the DocsViewer module (master branch) to the /docsviewer folder at the document root and ran /dev/build.

When I try to access http://localhost/dev/docs, I get the errors below. We had docsviewer working in 2.4.x. What is the SS version requirement for the current version of docsviewer?

thanks,
Steve

[Warning] Missing argument 2 for DocumentationViewer::handleAction(), called in /Users/steve/__projects/quinn.com/etc/305_docroot/framework/control/RequestHandler.php on line 184 and defined
GET /dev/docs
Line 134 in /Users/steve/__projects/quinn.com/etc/305_docroot/docsviewer/code/controllers/DocumentationViewer.php
Source
125     /**
126      * Overloaded to avoid "action doesn't exist" errors - all URL parts in 
127      * this controller are virtual and handled through handleRequest(), not 
128      * controller methods.
129      *
130      * @param $request
131      * @param $action
132      * @return SS_HTTPResponse
133      */
134     public function handleAction($request, $action) {
135         try {
136             $response = parent::handleAction($request, $action);
137         } catch(SS_HTTPResponse_Exception $e) {
138             if(strpos($e->getMessage(), 'does not exist') !== FALSE) {
139                 return $this;
140             } else {
Trace
DocumentationViewer->handleAction(SS_HTTPRequest) 
RequestHandler.php:184
RequestHandler->handleRequest(SS_HTTPRequest,DataModel) 
Controller.php:153
Controller->handleRequest(SS_HTTPRequest,DataModel) 
DocumentationViewer.php:176
DocumentationViewer->handleRequest(SS_HTTPRequest,DataModel) 
Director.php:296
Director::handleRequest(SS_HTTPRequest,Session,DataModel) 
Director.php:119
Director::direct(/dev/docs,DataModel) 
main.php:126
[User Warning] None of these templates can be found in theme 'simple': DocFolderListing.ss
GET /dev/docs
Line 670 in /Users/steve/__projects/quinn.com/etc/305_docroot/framework/view/SSViewer.php
Source
661             $this->chosenTemplates = SS_TemplateLoader::instance()->findTemplates(
662                 $templateList, self::current_theme()
663             );
664         }
665 
666         if(!$this->chosenTemplates) {
667             $templateList = (is_array($templateList)) ? $templateList : array($templateList);
668 
669             user_error("None of these templates can be found in theme '"
670                 . self::current_theme() . "': ". implode(".ss, ", $templateList) . ".ss", E_USER_WARNING);
671         }
672     }
673     
674     /**
675      * Returns true if at least one of the listed templates exists.
676      *
Trace
None of these templates can be found in theme 'simple': DocFolderListing.ss 
SSViewer.php:670
SSViewer->__construct(DocFolderListing) 
ViewableData.php:325
ViewableData->renderWith(DocFolderListing) 
DocumentationViewer.php:652
DocumentationViewer->getContent() 
ViewableData.php:106
ViewableData->__get(Content) 
ViewableData.php:368
ViewableData->obj(Content,,,1,) 
ViewableData.php:408
ViewableData->cachedCall(Content,) 
ViewableData.php:421
ViewableData->hasValue(Content,,1) 
call_user_func_array(Array,Array) 
SSViewer.php:144
SSViewer_Scope->__call(hasValue,Array) 
SSViewer.php:490
SSViewer_DataPresenter->__call(hasValue,Array) 
SSViewer_DataPresenter->hasValue(Content,,1) 
.cache.framework.templates.Controller.ss:39
include(/private/var/folders/s2/r1m_qbxn1dn7fd0slybq9n_w0000gv/T/silverstripe-cache-Users-steve-__projects-quinn.com-etc-305_docroot/.cache.framework.templates.Controller.ss) 
SSViewer.php:838
SSViewer->includeGeneratedTemplate(/var/folders/s2/r1m_qbxn1dn7fd0slybq9n_w0000gv/T/silverstripe-cache-Users-steve-__projects-quinn.com-etc-305_docroot/.cache.framework.templates.Controller.ss,DocumentationViewer,,Array) 
SSViewer.php:910
SSViewer->process(DocumentationViewer) 
Controller.php:214
Controller->handleAction(SS_HTTPRequest,) 
DocumentationViewer.php:136
DocumentationViewer->handleAction(SS_HTTPRequest) 
RequestHandler.php:184
RequestHandler->handleRequest(SS_HTTPRequest,DataModel) 
Controller.php:153
Controller->handleRequest(SS_HTTPRequest,DataModel) 
DocumentationViewer.php:176
DocumentationViewer->handleRequest(SS_HTTPRequest,DataModel) 
Director.php:296
Director::handleRequest(SS_HTTPRequest,Session,DataModel) 
Director.php:119
Director::direct(/dev/docs,DataModel) 
main.php:126
[Warning] file_get_contents() [function.file-get-contents]: Filename cannot be empty
GET /dev/docs
Line 886 in /Users/steve/__projects/quinn.com/etc/305_docroot/framework/view/SSViewer.php
Source
877         if(isset($_GET['debug_profile'])) Profiler::mark("SSViewer::process", " for $template");
878         $cacheFile = TEMP_FOLDER . "/.cache" 
879             . str_replace(array('\\','/',':'), '.', Director::makeRelative(realpath($template)));
880 
881         $lastEdited = filemtime($template);
882 
883         if(!file_exists($cacheFile) || filemtime($cacheFile) < $lastEdited || isset($_GET['flush'])) {
884             if(isset($_GET['debug_profile'])) Profiler::mark("SSViewer::process - compile", " for $template");
885             
886             $content = file_get_contents($template);
887             $content = SSViewer::parseTemplateContent($content, $template);
888             
889             $fh = fopen($cacheFile,'w');
890             fwrite($fh, $content);
891             fclose($fh);
892 
Trace
file_get_contents() 
SSViewer.php:886
SSViewer->process(ViewableData_Customised,) 
ViewableData.php:335
ViewableData->renderWith(DocFolderListing) 
DocumentationViewer.php:652
DocumentationViewer->getContent() 
ViewableData.php:106
ViewableData->__get(Content) 
ViewableData.php:368
ViewableData->obj(Content,,,1,) 
ViewableData.php:408
ViewableData->cachedCall(Content,) 
ViewableData.php:421
ViewableData->hasValue(Content,,1) 
call_user_func_array(Array,Array) 
SSViewer.php:144
SSViewer_Scope->__call(hasValue,Array) 
SSViewer.php:490
SSViewer_DataPresenter->__call(hasValue,Array) 
SSViewer_DataPresenter->hasValue(Content,,1) 
.cache.framework.templates.Controller.ss:39
include(/private/var/folders/s2/r1m_qbxn1dn7fd0slybq9n_w0000gv/T/silverstripe-cache-Users-steve-__projects-quinn.com-etc-305_docroot/.cache.framework.templates.Controller.ss) 
SSViewer.php:838
SSViewer->includeGeneratedTemplate(/var/folders/s2/r1m_qbxn1dn7fd0slybq9n_w0000gv/T/silverstripe-cache-Users-steve-__projects-quinn.com-etc-305_docroot/.cache.framework.templates.Controller.ss,DocumentationViewer,,Array) 
SSViewer.php:910
SSViewer->process(DocumentationViewer) 
Controller.php:214
Controller->handleAction(SS_HTTPRequest,) 
DocumentationViewer.php:136
DocumentationViewer->handleAction(SS_HTTPRequest) 
RequestHandler.php:184
RequestHandler->handleRequest(SS_HTTPRequest,DataModel) 
Controller.php:153
Controller->handleRequest(SS_HTTPRequest,DataModel) 
DocumentationViewer.php:176
DocumentationViewer->handleRequest(SS_HTTPRequest,DataModel) 
Director.php:296
Director::handleRequest(SS_HTTPRequest,Session,DataModel) 
Director.php:119
Director::direct(/dev/docs,DataModel) 
main.php:126

Problem on WAMP with Directory separator

Children menu in sidebar is not displaying due to DIRECTORY_SEPARATOR in function getChildrenFor in DocumentManifest.php (line 621)

        // only pull it up if it's one more level depth
        if(substr_count($pagePath,DIRECTORY_SEPARATOR ) == ($depth + 1)) {

should be

        // only pull it up if it's one more level depth
        if(substr_count($pagePath, '/') == ($depth + 1)) {

Add "last changed" status for each page

Knowing how "up to date" a piece of docs is can be important for the reader - e.g. you wouldn't trust a DataObject? API that was last updated in 2007.

This relies on the page inspecting the svn/git status of a module checkout, and looking at the properties for a specific file. Please ensure this does not harm rendering performance too much - if it does, we need to cache this information.

Composer update fails

Composer update now fails due to some branch changes in an external module. There error I'm getting is:

    - silverstripe/docsviewer dev-master requires erusev/parsedown dev-fixgreaterthan as ~1.0 -> no matching package found.
    - silverstripe/docsviewer dev-master requires erusev/parsedown dev-fixgreaterthan as ~1.0 -> no matching package found.
    - Installation request for silverstripe/docsviewer dev-master -> satisfiable by silverstripe/docsviewer[dev-master].

It looks like the fixgreaterthan branch has been removed from the module, but I don't know enough about this module to suggest a fix other than a guess that dev-master is probably ok now?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.