Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

which is the format of this documentation? #2

Open
nachinius opened this Issue · 20 comments

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
Owner

Its markdown

@fulopattila122

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

@fulopattila122

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

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

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

@beberlei
Owner

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

@jeserkin

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

@dominics

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

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

@beberlei
Owner
@fulopattila122

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

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

@dominics

@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

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

@jeserkin

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

@dominics

@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

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

@dominics

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