which is the format of this documentation? #2

Open
nachinius opened this Issue Mar 9, 2012 · 20 comments

Comments

Projects
None yet
6 participants
@nachinius

No README file to know how to parse this documentation in order to get something similar to what was on the web.

@beberlei

This comment has been minimized.

Show comment
Hide comment
@beberlei

beberlei Mar 9, 2012

Member

Its markdown

Member

beberlei commented Mar 9, 2012

Its markdown

@fulopattila122

This comment has been minimized.

Show comment
Hide comment
@fulopattila122

fulopattila122 Mar 13, 2012

What did you use to display it? I downloaded php-markdown 1.2.5, but doesn't display everything correctly. Eg. tables and +++ headings don't get transcoded.

And how did you generate that toc we used to have on the right?

So many questions.. :)

What did you use to display it? I downloaded php-markdown 1.2.5, but doesn't display everything correctly. Eg. tables and +++ headings don't get transcoded.

And how did you generate that toc we used to have on the right?

So many questions.. :)

@GromNaN

This comment has been minimized.

Show comment
Hide comment
@fulopattila122

This comment has been minimized.

Show comment
Hide comment
@fulopattila122

fulopattila122 Mar 14, 2012

.. neither :)

I know Doctrine 1 is retired, still there are folks using it out there, so the documentation is quite important for us.
Should we convert it to standard markdown format? Will we break any dependency with it?

What do you Doctrine guys recommend?

.. neither :)

I know Doctrine 1 is retired, still there are folks using it out there, so the documentation is quite important for us.
Should we convert it to standard markdown format? Will we break any dependency with it?

What do you Doctrine guys recommend?

@jeserkin

This comment has been minimized.

Show comment
Hide comment
@jeserkin

jeserkin Mar 15, 2012

Contributor

I don't understand at all why it was removed. The majority is using doctrine 1.2.x. Is it so hard to place it on the web somewhere as it was before? If it is so old and you don't support it, just place depricated somewhere, but removing whole web documentation on 1.2.x was not a smart thing to do.

Contributor

jeserkin commented Mar 15, 2012

I don't understand at all why it was removed. The majority is using doctrine 1.2.x. Is it so hard to place it on the web somewhere as it was before? If it is so old and you don't support it, just place depricated somewhere, but removing whole web documentation on 1.2.x was not a smart thing to do.

@nachinius

This comment has been minimized.

Show comment
Hide comment
@nachinius

nachinius Mar 15, 2012

I read in the doctrine mailing list that it was a mistake, and they will fix it soon.

On Mar 15, 2012, at 18:13, Eugene Serkinreply@reply.github.com wrote:

I don't understand at all why it was removed. The majority is using doctrine 1.2.x. Is it so hard to place it on the web somewhere as it was before? If it is so old and you don't support it, just place depricated somewhere, but removing whole web documentation on 1.2.x was not a smart thing to do.


Reply to this email directly or view it on GitHub:
#2 (comment)

I read in the doctrine mailing list that it was a mistake, and they will fix it soon.

On Mar 15, 2012, at 18:13, Eugene Serkinreply@reply.github.com wrote:

I don't understand at all why it was removed. The majority is using doctrine 1.2.x. Is it so hard to place it on the web somewhere as it was before? If it is so old and you don't support it, just place depricated somewhere, but removing whole web documentation on 1.2.x was not a smart thing to do.


Reply to this email directly or view it on GitHub:
#2 (comment)

@jeserkin

This comment has been minimized.

Show comment
Hide comment
@jeserkin

jeserkin Mar 15, 2012

Contributor

@nachinius yeah, read it too. Found a temporary solution http://goo.gl/P6ZRo

Contributor

jeserkin commented Mar 15, 2012

@nachinius yeah, read it too. Found a temporary solution http://goo.gl/P6ZRo

@beberlei

This comment has been minimized.

Show comment
Hide comment
@beberlei

beberlei Mar 15, 2012

Member

we relaunched the website on sphinx and forgot to migrate the doctrine 1.2 docs.

Member

beberlei commented Mar 15, 2012

we relaunched the website on sphinx and forgot to migrate the doctrine 1.2 docs.

@jeserkin

This comment has been minimized.

Show comment
Hide comment
@jeserkin

jeserkin Mar 16, 2012

Contributor

@beberlei will you anounce somewhere when it will be fixed?

Contributor

jeserkin commented Mar 16, 2012

@beberlei will you anounce somewhere when it will be fixed?

@dominics

This comment has been minimized.

Show comment
Hide comment
@dominics

dominics Mar 19, 2012

Contributor

What flavour of markdown is it? I didn't have a lot of success using pandoc to translate it from markdown to reStructuredText, but I'm attacking what didn't come across nicely with Vim macros and the like on this fork: https://github.com/dominics/doctrine1-documentation. It's a somewhat lossy automatic conversion, but I've been editing the markup to use reST's (more comprehensive) features and semantics (including sphinxcontrib-phpdomain) where I can.

For now, I'm pushing to http://readthedocs.org/docs/doctrine/en/latest/en/index.html - it's nicer than reading the raw source on github (without line wrapping!), has code fragment highlighting, and it's searchable.

There'll probably need to be a reST translation to get the old documentation onto the new official Sphinx documentation setup anyway. I just got sick of waiting.

Contributor

dominics commented Mar 19, 2012

What flavour of markdown is it? I didn't have a lot of success using pandoc to translate it from markdown to reStructuredText, but I'm attacking what didn't come across nicely with Vim macros and the like on this fork: https://github.com/dominics/doctrine1-documentation. It's a somewhat lossy automatic conversion, but I've been editing the markup to use reST's (more comprehensive) features and semantics (including sphinxcontrib-phpdomain) where I can.

For now, I'm pushing to http://readthedocs.org/docs/doctrine/en/latest/en/index.html - it's nicer than reading the raw source on github (without line wrapping!), has code fragment highlighting, and it's searchable.

There'll probably need to be a reST translation to get the old documentation onto the new official Sphinx documentation setup anyway. I just got sick of waiting.

@jeserkin

This comment has been minimized.

Show comment
Hide comment
@jeserkin

jeserkin Mar 19, 2012

Contributor

@dominics could you add some code highlighting, if possible? A bit hard to distinguish what is what, but doable.

Contributor

jeserkin commented Mar 19, 2012

@dominics could you add some code highlighting, if possible? A bit hard to distinguish what is what, but doable.

@beberlei

This comment has been minimized.

Show comment
Hide comment
@beberlei

beberlei Mar 19, 2012

Member

@dominic - Can you open a PR for your changes? I will add our theme, merge
it and then we can integrate back into the site. I wanted to do the same
after other options i tried failed.

On Mon, Mar 19, 2012 at 9:51 AM, Eugene Serkin <
reply@reply.github.com

wrote:

@dominics could you add some code highlighting, if possible? A bit hard to
distinguish what is what, but doable.


Reply to this email directly or view it on GitHub:

#2 (comment)

Member

beberlei commented Mar 19, 2012

@dominic - Can you open a PR for your changes? I will add our theme, merge
it and then we can integrate back into the site. I wanted to do the same
after other options i tried failed.

On Mon, Mar 19, 2012 at 9:51 AM, Eugene Serkin <
reply@reply.github.com

wrote:

@dominics could you add some code highlighting, if possible? A bit hard to
distinguish what is what, but doable.


Reply to this email directly or view it on GitHub:

#2 (comment)

@fulopattila122

This comment has been minimized.

Show comment
Hide comment
@fulopattila122

fulopattila122 Mar 19, 2012

@dominics It's great that you've made that available, thanks. However it still has some parts not appearing correctly, particularly tables. I'd be so curious what was the tool originally it got parsed/displayed with :)

@dominics It's great that you've made that available, thanks. However it still has some parts not appearing correctly, particularly tables. I'd be so curious what was the tool originally it got parsed/displayed with :)

@beberlei

This comment has been minimized.

Show comment
Hide comment
@beberlei

beberlei Mar 19, 2012

Member

the original tool is some weird script inside github.com/doctrine/doctrine-website

Member

beberlei commented Mar 19, 2012

the original tool is some weird script inside github.com/doctrine/doctrine-website

@dominics

This comment has been minimized.

Show comment
Hide comment
@dominics

dominics Mar 19, 2012

Contributor

@jeserkin @fulopattila122 I'm going through by hand and correcting the markup, focusing on getting the English manual done before the cookbook (and I don't know what I'm going to do for the Japanese manual). For example:

Converted: http://readthedocs.org/docs/doctrine/en/latest/en/manual/introduction-to-models.html
Not converted: http://readthedocs.org/docs/doctrine/en/latest/en/manual/defining-models.html

So, yes, it will all be pretty-looking soon. The Vim functions I've been using are in the TODO file, although I'm not sure they'll be useful to anyone else. It's slow going: a page takes me about twenty minutes to fix up.

@beberlei Happy to send a PR, but maybe we want to hold off until it's a bit more readable? Otherwise, feel free to use the fork queue I guess. Or ping me back and I'll send one.

Contributor

dominics commented Mar 19, 2012

@jeserkin @fulopattila122 I'm going through by hand and correcting the markup, focusing on getting the English manual done before the cookbook (and I don't know what I'm going to do for the Japanese manual). For example:

Converted: http://readthedocs.org/docs/doctrine/en/latest/en/manual/introduction-to-models.html
Not converted: http://readthedocs.org/docs/doctrine/en/latest/en/manual/defining-models.html

So, yes, it will all be pretty-looking soon. The Vim functions I've been using are in the TODO file, although I'm not sure they'll be useful to anyone else. It's slow going: a page takes me about twenty minutes to fix up.

@beberlei Happy to send a PR, but maybe we want to hold off until it's a bit more readable? Otherwise, feel free to use the fork queue I guess. Or ping me back and I'll send one.

@fulopattila122

This comment has been minimized.

Show comment
Hide comment
@fulopattila122

fulopattila122 Mar 19, 2012

@beberlei, @dominics Thank you guys for your kind replies. I really appreciate your work.

@beberlei, @dominics Thank you guys for your kind replies. I really appreciate your work.

@jeserkin

This comment has been minimized.

Show comment
Hide comment
@jeserkin

jeserkin Mar 29, 2012

Contributor

@dominics could I be of any service with preparing documentation or you have already finished?

Contributor

jeserkin commented Mar 29, 2012

@dominics could I be of any service with preparing documentation or you have already finished?

@dominics

This comment has been minimized.

Show comment
Hide comment
@dominics

dominics Mar 29, 2012

Contributor

@jeserkin Sure, thanks for the offer. So far I've been working on all the English manual chapters up to and including 'Component Overview'. So, if anyone wants to help, I recommend they grab one of the later chapters.

I'll try to keep the TODO up to date with my progress. Between that and the .vimfunctions file (if you can read vimL), you should be able to figure out what I've been doing.

Code examples and tables are the major issues.

Contributor

dominics commented Mar 29, 2012

@jeserkin Sure, thanks for the offer. So far I've been working on all the English manual chapters up to and including 'Component Overview'. So, if anyone wants to help, I recommend they grab one of the later chapters.

I'll try to keep the TODO up to date with my progress. Between that and the .vimfunctions file (if you can read vimL), you should be able to figure out what I've been doing.

Code examples and tables are the major issues.

@jeserkin

This comment has been minimized.

Show comment
Hide comment
@jeserkin

jeserkin Mar 30, 2012

Contributor

@dominics Is there some easy way to view my progress or only by commiting and viewing at least on github?

Contributor

jeserkin commented Mar 30, 2012

@dominics Is there some easy way to view my progress or only by commiting and viewing at least on github?

@dominics

This comment has been minimized.

Show comment
Hide comment
@dominics

dominics Mar 30, 2012

Contributor

@jeserkin I'm viewing the result of my work on a local webserver.

I installed python, pygments, sphinx, pip (for pip install sphinxcontrib-phpdomain), make, etc. Now I can run make html in the root directory of the project. This outputs the HTML documentation in the build directory (I then link that into /var/www/ so I can view it on a local webserver).

The only things different from readthedocs seem to be a different theme, and it not syntax-colouring quite the same number of languages: I get errors locally using .. code-block:: postgres, but it works fine once pushed to RTD.

Contributor

dominics commented Mar 30, 2012

@jeserkin I'm viewing the result of my work on a local webserver.

I installed python, pygments, sphinx, pip (for pip install sphinxcontrib-phpdomain), make, etc. Now I can run make html in the root directory of the project. This outputs the HTML documentation in the build directory (I then link that into /var/www/ so I can view it on a local webserver).

The only things different from readthedocs seem to be a different theme, and it not syntax-colouring quite the same number of languages: I get errors locally using .. code-block:: postgres, but it works fine once pushed to RTD.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment