Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

which is the format of this documentation? #2

Open
nachinius opened this Issue March 09, 2012 · 20 comments

6 participants

nachinius Benjamin Eberlei Attila Fulop Jérôme Tamarelle Eugene Serkin Dominic Scheirlinck
nachinius

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

Benjamin Eberlei
Owner

Its markdown

Attila Fulop

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.. :)

Attila Fulop

.. 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?

Eugene Serkin

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
Eugene Serkin

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

Benjamin Eberlei
Owner

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

Eugene Serkin

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

Dominic Scheirlinck

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.

Eugene Serkin

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

Benjamin Eberlei
Owner
Attila Fulop

@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 :)

Benjamin Eberlei
Owner

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

Dominic Scheirlinck

@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.

Attila Fulop

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

Eugene Serkin

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

Dominic Scheirlinck

@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.

Eugene Serkin

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

Dominic Scheirlinck

@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
Something went wrong with that request. Please try again.