Comments (10)
Hm, it seems to be a new issue. Let's wait if it gets solved.
readthedocs/readthedocs.org#1884
from documentation.
I also found an article explaining how to use sphinx for MD
It's also briefly explained in the official RTD docs at http://docs.readthedocs.org/en/latest/getting_started.html?highlight=markdown#in-markdown. I tried because it looked promising but since the implementation is based on CommonMark it was a dead end for us. In its current form CommonMark is just a no go because its scope is so limited and the pace at which the project moves forward is really slow. Not even markdown tables are supported.
from documentation.
Thanks for your input @marcelstoer, you probably saved us a lot of time.
Leaving this open until the linked issue is resolved.
from documentation.
I don't intend to lead you away from Sphinx & CommonMark, not at all. Do you own analysis by all means.
I spent some time reading through the CommonMark community postings and their current issues to get a feeling for what their intent is and how they go about things. As much as I like to idea of a Markdown "standard" I realized that my own ideas don't align very well with the CommonMark project so I didn't pursue that any further.
MkDocs and RTD have their own issues (localization is weird, not PDF/HTML export), I keep finding more and more bugs (mkdocs/mkdocs#774, mkdocs/mkdocs#770, mkdocs/mkdocs-bootswatch#5). So, I'm not really happy but I haven't found a better alternative yet.
from documentation.
The only reason I wanted to experiment with Sphinx is the issue linked above.
To tell the truth, I am amazed how many people use Sphinx with all the mess it comes with. I am sure it is fully configurable, so I am speaking for myself, but out of the 5 tries, I simply stopped playing with sphinx each time because it's complicated, etc.
I can live without PDF export, so if one day I will have plenty of time, I will definitely try Sphinx. Until then: no thanks. 😉
from documentation.
i am using sphinx with restructured text (rst) with good success. see foshttpcache, symfony-cmf and also the symfony docs. i don't know how much symfony people struggled to get http://symfony.com/doc/ run smoothly, but for simpler cases like foshttpcache on readthedocs it works nicely.
not saying we should convert everything from markdown to rst now (we had that discussion before) but maybe sphinx just works better with rst than md.
from documentation.
sphinx just works better with rst than md
That's something I agree with.
Another thing: the readthedocs theme with mkdocs does not really handle 3 level deep paths. Is the "original" theme with sphinx and rst better in it?
from documentation.
from documentation.
Maybe we should also limit to two level?
from documentation.
I guess this isn't relevant anymore.
from documentation.
Related Issues (20)
- Add documentation on plugin decoration.
- [CachePlugin] document hash key generator
- the doc about the bundle talks about deprecated configuration settings HOT 1
- Update symfony profiler screenshots
- [cache] document the hash_algo option
- [framework integration] Integration for Nette FW HOT 3
- MultiPart Request return Error: escapeshellarg(): Input string contains NULL bytes HOT 1
- Add docs about artax-adapter
- PluginClientFactory documentation HOT 2
- HTTPlug Maturity Model HOT 5
- Symfony bundle docs advise against proper TLS HOT 2
- Testing doc section for dev branch only HOT 6
- Update documentation on RetryPlugin HOT 2
- a client service or alias has been removed HOT 5
- Document RequestMatcherPlugin
- Document conditional with MockClient::on HOT 2
- Curl configuration raises a warning HOT 3
- No PSR-17 stream factory found, but I have one installed HOT 4
- Documentation search does not work HOT 1
- Class *** Not Found issue in php-http/discovery HOT 4
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
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.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from documentation.