move website into main repo #931

aciccarello · 2018-12-29T06:31:03Z

This moves the TypeStrong/typedoc-site repo into this project to make it easier to update the API docs and for contributors to find the website source.

See the changes since 90bc192 for the changes to the website.

Closes #604
Closes #658
Closes TypeStrong/typedoc-site#6
Closes TypeStrong/typedoc-site#8

Closes #4

The .nojekyll file didn't work b/c it needs to be in the root. These changes are untested because Windows...

Updating doccomments to include a few other javadoc tags

git-subtree-dir: website git-subtree-mainline: 6d5b21b git-subtree-split: d1e3895

used on guide layout closes typedoc/typedoc-site#8

reverted rename of Installation page to Usage

9oelM

Checked several parts of the website. Focused on fixing things that are supposed to work and adding possibly useful info.

9oelM · 2018-12-29T15:07:56Z

website/_sass/components/_home.sass

+        height: 100%
+        background-image: url(../images/jumbotron.png)
+        background-position: center center
+


Hey @aciccarello, I have made a build with jekyll and am looking into the website.

It was always a pain to see typedoc "visual" cut on the edge on my phone, like:

If you add

Suggested change

background-size: cover

It's going to be 200% prettier!

9oelM · 2018-12-29T15:29:01Z

website/_includes/header.html

@@ -0,0 +1,12 @@
+<header>
+    <div class="container">
+        <a href="{{ site.baseurl }}" class="logo">TypeDoc</a>


this line produces

<a href="" class="logo">TypeDoc</a>

and does nothing if you click on it. And this is what's actually happening in the current typedoc website. I know baseurl is defined in _config.yml but it seems you cannot access it by writing {{ site.baseurl }} (official doc appears to have no site.baseurl).

If you have made it an <a> tag, I suspect it's intended to redirect to the index page.
If you meant so, we could just

Suggested change

<a href="{{ site.baseurl }}" class="logo">TypeDoc</a>

<a href="/" class="logo">TypeDoc</a>

9oelM · 2018-12-29T16:07:47Z

website/_includes/head.html

+    <title>{{ page.title }} | TypeDoc</title>
+    <meta name="description" content="A documentation generator for TypeScript projects." />
+    <meta name="keywords" content="TypeScript documentation generator javascript open source" />
+


Perhaps add some og tags? It will help typedoc gain more exposure and be shared more easily.

Suggested change



<meta property="og:url" content="{{ page.url | absolute_url }}">

<meta property="og:description" content="A documentation generator for TypeScript projects.">

<meta property="og:title" content="{{ page.title }}">

<meta property="og:type" content="website" />

<meta property="og:site_name" content="{{ site.title }}">

<meta property="og:image" content="{{ "/images/logo-256.png" | absolute_url }}" />



<meta itemprop="name" content="{{ page.title }}">

<meta itemprop="description" content="A documentation generator for TypeScript projects.">



<meta name="twitter:card" content="{{ site.title }}">

<meta name="twitter:url" content="{{ page.url | absolute_url }} ">

<meta name="twitter:title" content="{{ page.title }}">

<meta name="twitter:description" content="A documentation generator for TypeScript projects.">

9oelM · 2018-12-29T16:14:25Z

website/_guides/doccomments.md

+All comments are parsed as markdown. TypeDoc uses the [Marked](<https://github.com/chjj/marked>) markdown parser
+and [HighlightJS](<https://github.com/isagalaev/highlight.js>) to highlight code blocks within markdown sections.
+Additionally you can link to other classes, members or functions using double square brackets.
+


@aciccarello are you going to add a note about #917 as well here?

I would like to. I wasn't sure if I wanted to do that in this PR or a follow up one. If I have time I'll add it.

9oelM · 2018-12-29T16:26:42Z

@aciccarello
@cancerberoSgx

Is there any chance #11 in typedoc-site repo will come alive together? It seems to be a really good resource.

9oelM · 2018-12-29T16:40:50Z

website/_guides/arguments.md

+```
+
+Exclude files by the given pattern when a path is provided as source
+


Add a note on excluding multiple patterns, as many people wonder how. As of now, the best practice appears to be put an array of strings of patterns to exclude inside typedoc.js as specified by @dupski in #170.

Suggested change

Multiple files could also be excluded by adding an array of strings in the `exclude` key of `typedoc.js` like this:

```js

module.exports = {

out: './docs/dist/api/',

readme: 'none',

includes: './',

exclude: [

'**/__tests__/**/*',

'**/__test_utils__/**/*',

'**/__fixtures__/**/*',

'**/testsuite/**/*'

],

mode: 'file',

excludeExternals: true,

excludeNotExported: true,

excludePrivate: true

};

```

Gerrit0

Do we really need to include the generated files in both this repo and the typedoc-site repo? I'd rather not require checkouts to pull in so many generated html files.

Gerrit0 · 2018-12-30T02:53:30Z

website/_guides/installation.md

+Plugins are available for Grunt, Gulp, and Webpack. All of them can be installed using ``npm``.
+
+
+### Grunt


I was under the impression that no grunt plugin was required for typedoc, why else do we have tasks/typedoc.js?

I don't use grunt anywhere else, but the linked plugin hasn't been updated in years.

That's been in the docs for years. I assume the grunt plugin still works and I think it'd be worth leaving it in there if it does.

9oelM · 2018-12-31T05:59:43Z

@Gerrit0 What do you exactly mean by the generated files? Do you mean the ones for typedoc api generated by typedoc under website/api/?

Gerrit0 · 2018-12-31T06:05:19Z

Yes, if all the html pages are being pushed to another repo, I don't see the need to track them here as well.

9oelM · 2018-12-31T06:05:34Z

You are right. we do not really need to include those htmls in website/api. Actually we could write some short travis scripts to automatically typedoc --out website/api/ src/index.ts on cloud and deploy the page to github pages, without needing to track them anywhere. This is going to keep the documentation up to date every time the website is deployed, which is going to automate the process as well.

And doesn't @aciccarello have a plan to archive/delete typedoc-site?

aciccarello · 2018-12-31T15:09:50Z

👍 Yeah, we shouldn't have the generated api files in here.

ATM, I'm planning on using gh-pages to push to the typedoc-site repo. If we want to move things to a gh-pages branch (which might make sense) we can do that later. But I don't have access to the website hosting so I didn't want to change any of that.

Gerrit0 · 2018-12-31T18:00:09Z

You should be able to change the website settings - I can see, and presumably change gh-pages settings here: https://github.com/TypeStrong/typedoc-site/settings

aciccarello · 2018-12-31T18:08:26Z

I knew about some of that config but assumed there would be some DNS config I couldn't access. We can look into it following this PR.

Gerrit0 · 2018-12-31T18:11:13Z

All GitHub pages sites use the same DNS configuration, so no changes should be required there. I agree - that change can wait until after the site is complete.

9oelM · 2019-01-08T03:14:13Z

Any updates?

cancerberoSgx · 2019-01-08T18:09:04Z

@9oelM @aciccarello hello, I can review the tutorial and perhaps remove a couple of sections that were kind of a research, like the event emitter one or make it shorter, I really don't have much time to invest on this, but if you think it will be merged so the doc is public I can make some time for this :P Somebody told me that this project is kind of obsolete in favor of other (i think it was ts-doc from microsoft) but I tried it some month ago and is not as mature as typedoc (features and ecosystem) . Is this right or I misunderstood, what's the situation here so is worthwhile to invest on this ? Thanks and keep it up, I think with a little more documentation this tool is great, even compared to jsdoc (JavaScript's) ones.

aciccarello · 2019-01-08T18:13:09Z

@9oelM @cancerberoSgx I still plan on updating this based on the feedback. From there we can merge this update and move towards improving the docs. Eventually I would like to add the tutorial @cancerberoSgx worked on but this is a first step to making it easier to work on the website.

cancerberoSgx · 2019-01-08T18:15:17Z

Nice! will try to review the tutorial and remove research-sections and references to some plugins that I think the tutorial adds, so is more basic, thanks

cancerberoSgx · 2019-01-09T02:23:35Z

@aciccarello should I keep working on typedoc--site PR TypeStrong/typedoc-site#11 or do you think is better to start using this PR and integrate the tutorial here ? In the first case I wonder how difficult would be to re-integrate the changes in obsolete repo typedoc-site, thanks

aciccarello · 2019-01-09T15:55:45Z

@cancerberoSgx This PR is mostly a copy from typedoc-site but it is is probably easiest to work off of this PR

aciccarello · 2019-02-08T06:47:36Z

Thanks for all the feedback. I've decided to not move the content into this repo to keep things simpler. This work has been continued in TypeStrong/typedoc-site#12.

We should update the contributing guide to link to the content.

d-asensio and others added 29 commits August 26, 2016 01:01

TypeDoc site written in Jekyll.

e00526e

CNAME added and page URL configured for typedoc.org

dd663e3

Changed the default page of guides to lowwercase.

d1da035

Changed default guide to installation

2a957d9

API menu hidden

251ea24

TypeDoc API documentation added.

c51acf1

API menu hidden again, some issues detected.

f1e9e26

Correct documentation for references (#3)

348a487

fix publishing of files starting with underscore

cdc16a3

Closes #4

include api files starting with underscore

30b88da

The .nojekyll file didn't work b/c it needs to be in the root. These changes are untested because Windows...

Adjust include glob

99b9645

update api documentation

d4b81c6

add api link to header

4bd87a4

update documentation following v0.10.0 release

96e15f6

Updating doccomments to include other javadoc tags

fed9d5c

Merge pull request #9 from ice1080/javadocTags

44023fa

Updating doccomments to include a few other javadoc tags

Update dependencies

8e81fca

Delete CNAME

77e0b0e

Create CNAME

d1e3895

Add 'website/' from commit 'd1e38958b72c838f6379fef67a88277004fceb06'

90bc192

git-subtree-dir: website git-subtree-mainline: 6d5b21b git-subtree-split: d1e3895

Add deploy command

c6de7c0

Rename module to namespace in docs

e8042e2

Add configuration options to usage guide

eb91a86

Clean up usage docs

5fa26ff

update guides

f70ab9a

support single column mobile layout

2e8a852

used on guide layout closes typedoc/typedoc-site#8

add redirect to arguments page

e7d1121

reverted rename of Installation page to Usage

add starter website deploy script

8675e6f

Add additional contributing information

afd4d1f

9oelM suggested changes Dec 29, 2018

View reviewed changes

9oelM reviewed Dec 29, 2018

View reviewed changes

Gerrit0 reviewed Dec 30, 2018

View reviewed changes

Gerrit0 mentioned this pull request Jan 21, 2019

typedoc Restructure #595

Closed

9 tasks

aciccarello mentioned this pull request Feb 8, 2019

Rework guides TypeStrong/typedoc-site#12

Merged

aciccarello closed this Feb 8, 2019

Gerrit0 deleted the add-docs branch January 14, 2020 20:05

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

move website into main repo #931

move website into main repo #931

aciccarello commented Dec 29, 2018

9oelM left a comment •

edited

Loading

9oelM Dec 29, 2018 •

edited

Loading

9oelM Dec 29, 2018 •

edited

Loading

9oelM Dec 29, 2018 •

edited

Loading

9oelM Dec 29, 2018 •

edited

Loading

aciccarello Dec 29, 2018

9oelM Dec 31, 2018

9oelM commented Dec 29, 2018

9oelM Dec 29, 2018 •

edited

Loading

Gerrit0 left a comment

Gerrit0 Dec 30, 2018

aciccarello Dec 31, 2018

9oelM commented Dec 31, 2018 •

edited

Loading

Gerrit0 commented Dec 31, 2018

9oelM commented Dec 31, 2018 •

edited

Loading

aciccarello commented Dec 31, 2018

Gerrit0 commented Dec 31, 2018

aciccarello commented Dec 31, 2018

Gerrit0 commented Dec 31, 2018

9oelM commented Jan 8, 2019

cancerberoSgx commented Jan 8, 2019

aciccarello commented Jan 8, 2019

cancerberoSgx commented Jan 8, 2019

cancerberoSgx commented Jan 9, 2019

aciccarello commented Jan 9, 2019

aciccarello commented Feb 8, 2019

	<a href="{{ site.baseurl }}" class="logo">TypeDoc</a>
	<a href="/" class="logo">TypeDoc</a>

+<!--facebook-->
+<meta property="og:url" content="{{ page.url | absolute_url }}">
+<meta property="og:description" content="A documentation generator for TypeScript projects.">
+<meta property="og:title" content="{{ page.title }}">
+<meta property="og:type"   content="website" />
+<meta property="og:site_name" content="{{ site.title }}">
+<meta property="og:image"  content="{{ "/images/logo-256.png" | absolute_url }}" />
+<!--google+-->
+<meta itemprop="name" content="{{ page.title }}">
+<meta itemprop="description" content="A documentation generator for TypeScript projects.">
+<!--Twitter-->
+<meta name="twitter:card" content="{{ site.title }}">
+<meta name="twitter:url" content="{{ page.url | absolute_url }} ">
+<meta name="twitter:title" content="{{ page.title }}">
+<meta name="twitter:description" content="A documentation generator for TypeScript projects.">

		```

		Exclude files by the given pattern when a path is provided as source

+  Multiple files could also be excluded by adding an array of strings in the `exclude` key of `typedoc.js` like this:
+    ```js
+    module.exports = {
+      out: './docs/dist/api/',
+      readme: 'none',
+      includes: './',
+      exclude: [
+          '**/__tests__/**/*',
+          '**/__test_utils__/**/*',
+          '**/__fixtures__/**/*',
+          '**/testsuite/**/*'
+      ],
+      mode: 'file',
+      excludeExternals: true,
+      excludeNotExported: true,
+      excludePrivate: true
+    };
+    ```

		Plugins are available for Grunt, Gulp, and Webpack. All of them can be installed using ``npm``.


		### Grunt

move website into main repo #931

move website into main repo #931

Conversation

aciccarello commented Dec 29, 2018

9oelM left a comment • edited Loading

Choose a reason for hiding this comment

9oelM Dec 29, 2018 • edited Loading

Choose a reason for hiding this comment

9oelM Dec 29, 2018 • edited Loading

Choose a reason for hiding this comment

9oelM Dec 29, 2018 • edited Loading

Choose a reason for hiding this comment

9oelM Dec 29, 2018 • edited Loading

Choose a reason for hiding this comment

aciccarello Dec 29, 2018

Choose a reason for hiding this comment

9oelM Dec 31, 2018

Choose a reason for hiding this comment

9oelM commented Dec 29, 2018

9oelM Dec 29, 2018 • edited Loading

Choose a reason for hiding this comment

Gerrit0 left a comment

Choose a reason for hiding this comment

Gerrit0 Dec 30, 2018

Choose a reason for hiding this comment

aciccarello Dec 31, 2018

Choose a reason for hiding this comment

9oelM commented Dec 31, 2018 • edited Loading

Gerrit0 commented Dec 31, 2018

9oelM commented Dec 31, 2018 • edited Loading

aciccarello commented Dec 31, 2018

Gerrit0 commented Dec 31, 2018

aciccarello commented Dec 31, 2018

Gerrit0 commented Dec 31, 2018

9oelM commented Jan 8, 2019

cancerberoSgx commented Jan 8, 2019

aciccarello commented Jan 8, 2019

cancerberoSgx commented Jan 8, 2019

cancerberoSgx commented Jan 9, 2019

aciccarello commented Jan 9, 2019

aciccarello commented Feb 8, 2019

9oelM left a comment •

edited

Loading

9oelM Dec 29, 2018 •

edited

Loading

9oelM Dec 29, 2018 •

edited

Loading

9oelM Dec 29, 2018 •

edited

Loading

9oelM Dec 29, 2018 •

edited

Loading

9oelM Dec 29, 2018 •

edited

Loading

9oelM commented Dec 31, 2018 •

edited

Loading

9oelM commented Dec 31, 2018 •

edited

Loading